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Parti: User Commands 

Introduction 

This section introduces and describes user commands. 

AUTHORS 

Look at the header of the manual page for the author(s) and copyright conditions N ote that these can be different from page 
to page. 

addftinfo 

addftinfo— Add information totroff fontfilesforusewith groft 

SYNOPSIS 

addftinfo [ -paramvalue... ] res unit width font 

DESCRIPTION 

addftinfo readsatnoff font file and adds some additional font-metric information that is used by thegroff system. The font 
filewith the information added is written on the standard output. The information added isguessed using some parametric 
information about thefontand assumptions about the traditional troff namesfor characters. The main information added 
is the heights and depths of characters. The res and unitwidth arguments should be the same as the corresponding param¬ 
eters in theDEsc file; font isthenameof thefile describing the font; if font ends with I, the font will be assumed to be italic. 

OPTIONS 

Each of the f options changes one of the parameters that is used to derive the heights and depths. Like the existing quantities 
in thefontfile, each value isin inche^res for a font whose point sizeisunitwidth. param mustbeoneof the following: 

x-height The height of lowercase letters without ascenders such asx 

fig-height T he height of figures (digits) 

asc-height T he height of characters with ascenders, such as b, d, or I 

body-height T he height of characters such as parentheses 

cap-height T he height of uppercase letters such asA 

comma-depth T he depth of a comma 

desc-depth Thedepth of characters with descenders, such asp, q, ory 

body-depth Thedepth of characters such as parentheses 

addftinfo makes no attempt to use the specified parameters to guess the unspecified parameters. If a parameter is not 
specified, the default will beused. The defaults are chosen to have the reasonable values for a Times font. 

SEE ALSO 

font(5) groff_font(5), groff(l), groff_char(7) 

Groff Verson 1.09, 6 August 1992 

afmtodit 

afmtodit- Create font files for use with groff -Tps 

SYNOPSIS 

afmtodit [ -ns ] [-ddescj i I e ][-eenc_fi I e ] [-in ] [-an ] a f m_ f i I e map_file font 
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DESCRIPTION 

afmtodit creates a font file for use with groff and grops. afmtodit is written in Perl; you must have Perl version 3 installed in 
order to run afmtodit. afm_fiie istheAFM (Adobe Font M etric) file for the font. map_fiie is a file that says which groff 
character names map onto each PostScript character name; thisfile should contain a sequence of lines of the form: 

ps_char groff char 

where ps_char is the PostScript name of the character and groff_char is the groff name of the character (as used in the groff 
font file) The same ps_char can occur multiple times in the file each groff_char must occur, at most, once, font is the groff 
name of the font. If a PostScript character is in the encoding to be used for the font but is not mentioned in map_fiie, then 
afmtodit will put it in the groff font file as an unnamed character, which can be accessed by the \n escape sequence in troff. 

T he groff_font file will be output to a file called font. 

If there is a downloadable font filefor the font, it may be listed in the file /usr/iib/grof f/font/devps/downioad; see grops(l). 

If the -i option is used, afmtodit will automatically generate an italic correction, a left italic correction, and a subscript 
correction for each character (the significance of these parameters is explained in groff_font(5)); these parameters may be 
specified for individual characters by adding to theafmfiie lines of the form: 

italicCorrectionps charn 
leftltalicCorrectionps charn 
subscriptCorrectionps charn 

where ps_char is the PostScript name of the character, and n is the desired value of the corresponding parameter in thou¬ 
sandths of an em. These parameters are normally needed only for italic (or oblique) fonts. 

OPTIONS 

-n Don't output a ligatures command for this font. Use this with constant-width fonts. 

-s The font is special. The effect of this option is to add the special command to the font file. 

-ddesc_f i i e The device description fileisdesc.fi i e rather than the default desc. 

- ee n c _f i i e T he PostScript font should be reencoded to use the encoding described inenc.fi i e. The format of 

enc.fi I e isdescribed in grops(l). 

-an Usen as the slant parameter in the font file; this is used by groff in the positioning of accents By 

default, afmtodit uses the negative of the itaiicAngie specified in theafm.fi i e; with true italic 
fonts, it is sometimes desirable to use a slant that is less than this. If you find that characters from 
an italic font have accents placed too far to the right over them, then use the -a option to give the 
font a smaller slant. 

-in Generate an italic correction for each character so that the character's width plus the character's 

italic correction is equal to n thousandths of an em plus the amount by which the right edge of the 
character's bounding is to the right of the character's origin. If this would result in a negative italic 
correction, use a zero italic correction instead. 

Also generate a subscri pt correction equal to the product of the tangent of the slant of the font and 
four-fifths of thex-heightof the font. If this would result in a subscript correction greater than the 
italic correction, use a subscript correction equal to the italic correction instead. 

Also generate a left italic correction for each character equal to n thousandths of an em plus the 
amount by which the left edge of the character's bounding box is to the left of the character's 
origin. The left italic correction may be negative. 

This option is normally needed only with italic (or oblique) fonts. The font files distributed with 
groff were created using an option of-iso for italic fonts 


FILES 

/ usr/lib/groff/font/devps/DESC 

/usr/lib/groff/font/devps/F 

/usr/lib/groff/font/devps/download 


Device description file 
Font description file for font f 
L ist of downloadable fonts 
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/usr/iib/groff/font/devps/text.enc Encoding used for text fonts 

/usr/lib/groff/font/devps/generate/textmap Standard mapping 

SEE ALSO 

groff(l), grops(l), groff_font(5), perl(l) 

Groff Version 1.09,14 February 1994 


ansi2knr 

ansi 2 knr— Convert AN SI C toKernighan& RitchieC 

SYNOPSIS 

ansi2knr i nput_fiI e output fi I e 

DESCRIPTION 

If no out put _f i i e is supplied, output goes to stdout. There are no error messages. 

ansi 2 knr recognizes functions by seeing a nonkeyword identifier at the left margin, followed by a left parenthesis, with a right 
parenthesis as the last character on the line. It will recognize a multiline header if the last character on each line but the last is 
a left parenthesis or comma. These algorithms ignore whitespace and comments, except that the function name must be the 
first thing on the line. 

T he following constructs will confuseit: 

■ Any other construct that starts at the left margin and follows the above syntax (such as a macro or function call) 

■ M acrosthattinkerwith the syntax of the function header 

31 December 1990 


anytopnm 

anytopnm— Attempt to convert an unknown type of image file to a portable anymap 

SYNOPSIS 

anytopnm file 

DESCRIPTION 

anytopnm uses the fi le program, possibly augmented by the magic numbers file included with pbmplus, to try to figure out 
what type of image file it is. If that fails (very few image formats have magic numbers), looks at the filename extension. If 
that fails, punt. 

T he type of the output fi le depends on the input file. 

SEE ALSO 

pnmfile(l), pnm(5), file(l) 

BUGS 

It's a script. Scripts are not portable to non-U N IX environments 

AUTHOR 

Copyright© 1991 byjef Poskanzer 


27]u\yl990 
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appres 

appres— List x application resource database 

SYNOPSIS 

appres [[class [instance]] [-1] [t ool ki t opt i ons ] 

DESCRIPTION 

The appres program prints the resources seen by an application (or subhierarchy of an application) with the sped tied class 
and instance names. It can be used to determine which resources a particular program will load. For example, 

% appres XTerm 

will list the resources that any xterm program will load. If no application class is specified, the class -AppResTest- is used. 

T o match a particular instance name specify an instance name explicitly after the class name, or use the normal xt toolkit 
option. For example, 

% appres XTerm myxterm 
or 

% appres XTerm -name myxterm 

To list resources that match a subhierarchy of an application, specify hierarchical class and instance names. The number of 
class and instance components must be equal, and the instance name should not be specified with atoolkit option. For 
example, 

% appres Xman.TopLevelShell.Form xman.topBox.form 

will list the resources of widgets of xman topBox hierarchy. To list just the resources matching a specific level in the hierarchy, 
use the-i option. For example, 

% appres XTerm.VT100 xterm.vt100 -1 

will list the resources matching thexterm vtiea widget. 

SEE ALSO 

X(l), xrdb(l), listres(l) 

AUTHOR 

Jim Fulton (M IT X Consortium) 

X Version 11 Release 6 


ar 

ar— C reate, modify, and extract from archives 

SYNOPSIS 

ar [ - ] dmpqrtx[abcilosuvV] [ membername ] archive files ... 

DESCRIPTION 

TheGN U ar program creates, modifies, and extracts from archives. An archive is a single fi le holding a collection of other 
filesin a structure that makes it possible to retri eve the original individual files (called members of thearchive). 

The original files' contents, mode (permissions), timestamp, owner, and group are preserved in thearchive, and may be 
reconstituted on extraction. 
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GN U ar can maintain archives whose members have names of any length; however, depending on how ar is configured on 
your system, alimiton member-name length may beimposd (for compatibility with archive formats maintained with other 
tools). If it exists, the limit is often 15 characters (typical of formats related to a. out) or 16 characters (typical of formats 
related to coft). 

ar is considered a binary utility because archives of this sort are most often used as libraries holding commonly needed 
subroutines. 

ar will create an index to the symbols defined in relocatable object modules in the archive when you specify the modifier s. 
Once created, this index is updated in the archive whenever ar makes a change to its contents (save for theq update 
operation). An archive with such an index speeds up I inking to the library, and allows routines in the library to call each 
other without regard to their placement in the archive. 

You may use nm -s or nm -print-armap to list this index table. If an archive lacks the table, another form of ar called raniib 
can be used to add just the table. 

ar insists on at least two arguments to execute: one keyletter specifying the operation (optionally accompanied by other 
keyletters specifying modifiers), and the archive name to act on. 

M ost operations can also accept further files arguments, specifying particular files to operate on. 

OPTIONS 

GN U ar allows you to mix the operation codep and modifier flags mod in any order, within the first command-line 
argument. 

If you wish, you may begin the first command-line argument with a dash. 

Thep keyletter specifies what operation to execute; it may beany of thefollowing, but you must specify only one of them: 

d Delete modules from the archive. Specify the names of modules to be deleted as files; the archive is 

untouched if you specify no files to delete. 

If you specify the v modifier, ar will list each module as it is deleted, 
m U se this operation to movemembersin an archive. 

The ordering of members in an archive can make a difference in how programs are linked using the 
library if a symbol is defined in more than one member. 

If no modifiers are used with m, any members you name in the files arguments are moved to the end of 
the archive; you can usethea, b, ori modifiers to move them to a specified place i nstead. 
p Print the specified membersof the archive to the standard output file. If thev modifier is specified, 

show the membername before copying its contents to standard output. 

If you specify no files, all the files in the archive are printed, 
q Quick append; add files to the end of archive without checking for replacement. 

The modifiers a, b, and i do not affect this operation; new members are always placed at the end of the 
archive. 

T he modifier v makes ar list each file as it is appended. 

Sincethe point of this operation is speed, the archive's symbol table index is not updated, even if it 
already existed; you can usear s or raniib explicitly to update the symbol table index, 
r Insert files into archive (with replacement). This operation differs from q in that any previously existing 

members are deleted if their names match those being added. 

If one of the files named in files doesn't exist, ar displays an error message and leaves undisturbed any 
existing membersof thearchive matching that name 

By default, new members are added at the end of the file, but you may use one of the modifiers a, b, or 
i to request placement relative to some existing member. 

The modifier v used with this operation elicits a line of output for each file inserted, along with one of 
thelettersa orrto indicate whether the filewas appended (no old member deleted) or replaced. 
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t D isplay a table listing the contents of archive, or those of the files listed in files that are present in the 

archive. N ormally, only the mem bername is shown; if you also want to seethe modes (permissions), 
timestamp, owner, group, and size, you can request that by also specifying thev modifier. 

If you do not specify any files, all filesin the archive are listed. 

If there is more than one file with the same name (say, tie) in an archive (say, b.a), ar t b.a fie will 
list only thefirst instance to see them all, you must ask for a complete listing— in our example, ar t 

b.a. 

x Extract members (named files) from the archive. You can use thev modifier with this operation to 

request that ar list each name as it extracts it. 

If you do not specify any files, all filesin the archive are extracted. 

A number of modifiers (mod) may immediately follow the p key letter, to specify variations on an operation's behavior, as 
follows: 

a Add new files after an existing member of the archive. If you use the modifier a, the name of an 

existing archive member must be present asthemembernameargument, before thearchive specifica¬ 
tion. 

b Add new files before an existing member of thearchive. If you use the modifier b, the name of an 

existing archive member must be present asthemembernameargument, before thearchive specifica¬ 
tion (same as i). 

c Create the archive. The specified archive is always created if it didn't exist when you request an update. 

But a warning is issued unless you specify in advance that you expect to create it by using this modifier, 
i Insert new files before an existing member of thearchive. If you use the modifier i, the name of an 

existing archive member must be present asthemembernameargument, before thearchive specifica¬ 
tion. (same as b). 

1 T his modifier is accepted but not used. 

o Preserve the original dates of members when extracting them. If you do not specify this modifier, files 

extracted from the archive will be stamped with the time of extraction, 
s Write an object-file index into thearchive, or update an existing one, even if no other change is made 

to thearchive. You may use this modifier flag either with any operation, or alone. Running ar s on an 
archive is equivalent to running raniib on it. 

u N ormally, ar r. .. insertsall files listed into thearchive. If you would liketo insert only those of the 

files you list that are newer than existing members of the same names, use this modifier. The u modifier 
is allowed only for the operation r (replace). In particular, the combi nation qu is not allowed, since 
checking thetimestamps would lose any speed advantage from theoperation q. 
v This modifier requests the verbose version of an operation. M any operations display additional 

information, such as filenames processed, when the modifier v is appended, 
v Thismodifiershowstheversion numberofar. 

SEE ALSO 

binutiis entry in info; The GNU Binary Utilities, Roland H. Pesch (October 1991); nm(l), aniib(l) 

COPYING 

Copyright © 1991 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this 
manual provided thecopyright notice and this permission notice are preserved on all copies. Permission isgranted to copy 
and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting 
derived work is distributed under the terms of a permission notice identical to this one. 

Permission isgranted to copy and distribute translations of this manual into another language, under the above conditions 
for modified versions, except that this permission notice may be included in translations approved by the Free Software 
Foundation instead of in the original English. 


CygnusSupport, 5 N ovemberl991 
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arch 

arch— Print architecture 

SYNOPSIS 

arch 

DESCRIPTION 

arch displays machi ne architecture type. 

SEE ALSO 

uname(l), uname(2) 

Debian GNU/Linux, 15 January 1994 


GNU as 

GNU as— The portable GN U assembler 

SYNOPSIS 

as [ -a -al | -as ][-D ][-f ] [-I path ][-K ][-L ][-o objfile ] [-R ][-v ][-w ][—\|\ 
files ... ] 

i960-only options 

[ -ACA] -ACA A I -ACB ] -ACC | -AKAj -AKB ] -AKC ] -AMC] [-b ][-no-relax ] 

m680x0-only options: 

[ -1 ][-mc680001 -mc68010j -mc68020] 

DESCRIPTION 

GN U as is really a family of assemblers. If you use (or have used) theGN U assembler on one architecture, you should find a 
fairly similar environment when you useiton another architecture. Each version hasmuch in common with theothers, 
including object file formats, most assembler directives (often called pseudo-ops) and assembler syntax. 

For information on the syntax and pseudo-ops used by GN U as, see as entry in info (or the manual Us/ngasTheGNU 
Assembler). 

as is primarily intended to assemble the output of theGN U C compiler gcc for use by the linker id. N evertheless, we've tried 
to make as assemble correctly everything that the native assembler would. This doesn't mean as always uses the same syntax 
as another assembler for the same architecture; for example, we know of several incompatible versions of 680x0 assembly 
language syntax. 

Each time you run as, it assembles exactly one source program. The source program is made up of one or more files. (The 
standard input is also a file.) 

If as is given no filenames, it attempts to read one input file from the as standard input, which is normally your terminal. 
You may haveto type Ctrl-D to tell as there is no more program to assemble. Use—if you need to explicitly name the 
standard input file in your command line. 

as may write warnings and error messages to the standard error file (usually your terminal). This should not happen when as 
is run automatically by a compiler. Warnings report an assumption made so that as could keep assembling a flawed program; 
errors report a grave problem that stops the assembly. 
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OPTIONS 

-a|-al|-as 

-D 

-f 

-I\p a t h 

-K 

-L 

—o\o bj file 

-R 

-v 

-W 

—\ J \f i I e s ... 
-Avar 

-b 

-no-relax 

-1 


-mc68000|-mc68010|-mc68020 


Turn on assembly listings; -ai, listing only, -as, symbolsonly, -a, everything. 

This option is accepted only for script compatibility with cal Is to other assemblers; it 
has no effect on as. 

"Fast"-skip preprocessing (assumesourceiscompiler output). 

Add path to the search list for .include directives. 

Issuewarningswhen difference tables altered for long displacements. 

Keep (in symbol table) local symbols, starting with L. 

N ame the object-file output from as. 

Fold data section into text section. 

Announce as version. 

Suppress warning messages. 

Source files to assemble, orstandard input (—). 

(W hen configured for Intel 960.) Specify which variant of the 960 architecture isthe 
target. 

(W hen configured for Intel 960.) Add code to collect statistics about branches taken. 
(W hen configured for Intel 960.) Do not alter compare-and-branch instructions for 
long displacements; error if necessary. 

(W hen configured for M otorola 68000.) Shorten references to undefined symbols to 
oneword instead of two. 

(W hen configured for M otorola 68000.) Specify which processor in the68000 
family is the target (default 68020 ). 


Options may be in any order, and may be before, after, or between filenames. The order of filenames is significant. 

The double hyphens command (-) by itself names the standard input file explicitly, as one of the files for as to assemble. 

Except for —, any command line argument that begins with a hyphen (-) is an option. Each option changes the behavior of 
as. N 0 option changes the way another option works An option is a hyphen followed by one or more letters; the case of the 
letter isimportant. All options are optional. 

The-o option expects exactly one filename to follow. Thefilename may either immediately follow the option's letter 
(compatible with older assemblers) or it may be the next command argument (G N U standard). 

These two command lines are equivalent: 
as -0 my-object-file.o mumble.s 


as -omy-object-file.o mumble.s 

SEE ALSO 

as entry in into; UsingasTheGNU Assembler ; gcc(l), id(l). 

COPYING 

Copyright © 1991,1992 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of 
thismanual provided the copyright notice and this permission notice are preserved on all copies. Permission isgranted to 
copy and distribute modified versions of thismanual under the conditions for verbatim copying, provided that the entire 
resulting derived work is distributed under the terms of a permission notice identical to this one 

Permission isgranted to copy and distribute translations of thismanual into another language, under the above conditions 
for modified versions, except that this permission notice may be included in translations approved by the Free Software 
Foundation instead of in the original English. 


CygnusSupport, 21 January 1992 
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asciitopgm 

asciitopgm — C onvert ASC11 graphics into a portable graymap 

SYNOPSIS 

asciitopgm [-d divisor] height width [ascii file] 

DESCRIPTION 

Reads ASC 11 data as input. Produces a portable graymap with pixel values that are an approximation of the brightness of the 
ASCII characters, assuming black-on-white printing. In other words, a capital M is very dark, a period is very light, and a 
spaceiswhite. Input lines that are fewer than width characters are automatically padded with spaces. 

T he divisor argument is a floati ng-point number by which the output pixels are divided; the default value isi . 0 . T his can be 
used to adjust the brightness of the graymap; for example, if the image is too di m, reduce the divisor. 

In keeping with (I believe) FORTRAN line-printer conventions, input lines beginning with a + (plus) character are assumed 
to overstri ke the previous line allowing a larger rangeof gray values. 

This tool contradicts the message in thepbmtoascii manual: "Note that there is no asciitopbm tool—this transformation is 
one-way.” 

BUGS 

The table of ASC II-to-gray values is subject to interpretation, and, of course, depends on the typeface intended for the input. 

SEE ALSO 

pbmtoascii(l), pgm(5) 

AUTHOR 

Wilson H . Bent, Jr. (whb@usc.edu) 

26 December 1994 


atktopbm 

atktopbm— Convert Andrew Toolkit raster object to portable bitmap 

SYNOPSIS 

atktopbm [at kfiI e ] 

DESCRIPTION 

atktopbm reads an Andrew Toolkit raster object as input and produces a portable bitmap as output. 

SEE ALSO 

pbmtoatk(l), pbm(5) 

AUTHOR 

Copyright © 1991 by Bill Janssen 


26 September 1991 
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bash—GNU Bourne-again shell 

SYNOPSIS 

bash [options] [file] 

DESCRIPTION 

bash is an sh-compatible command language interpreter that executes commands read from the standard input or from a file, 
bash also incorporates useful features from theKorn and C shells (ksh and csh). 

bash isultimately intended to beaconformant implementation of thelEEE POSIX Shell and Toolsspecification (IEEE 
Working Group 10032). 

OPTIONS 

In addition to the single-character shell options documented in the description of the set built-in command, bash interprets 
the following flags when it isinvoked: 

-c stri ng If the -c flag is present, then commands are read from stri ng . If there are arguments after the 

string, they are assigned to the positional parameters, starting with $ 0 . 

-i If the -i flag ispresent, theshell isinteractive. 

-s If the -s flag ispresent, or if no arguments remain after option processing, then commands are 

read from the standard input. This option allows the positional parameters to beset when 
invoking an interactive shell. 

A single- signals the end of options and disables further option processing. Any arguments after 
the - are treated as filenames and arguments. An argument of - is equivalent to an argument 
of -. 


bash also interprets a number of multicharacter options. T 0 be recognized, these options must appear on the command line 
before the single-character options. 


-norc 

-noprofile 


-rcfile file 

-version 

-quiet 

-login 

-nobraceexpansion 

-nolineediting 

-posix 


Do not read and execute the personal initialization file '/.bashrc if theshell isinteractive. This 
option ison by default if theshell isinvoked assh. 

Do not read either the system-wide startup file /etc/profiie or any of the personal initializa¬ 
tion files '/.bash_profiie ,7 ,bash_iogin, or '/.profile. By default, bash normally reads these 
files when it isinvoked as a login shell. (See the "Invocation" section, later in this manual page.) 
Execute commands from file instead of thestandard personal initialization file'/ .bashrc, if the 
shell isinteractive. (See"Invocation.”) 

Show theversion number of this instance of bash when starting. 

Do not be verbose when starting up (do not show theshell version or any other information). 
This is the default. 

M akebash act as if it had been invoked as a login shell. 

Do not perform curly brace expansion. (See "Brace Expansion," later in this manual page.) 

Do not use the GN U readiine library to read command lines if interactive. 

C hange the behavior of bash where the default operati on differs from the PO SI X 1003.2 
standard to match thestandard. 


ARGUMENTS 

If arguments remain after option processing, and neither the -c nor the -s option has been supplied, thefirst argument is 
assumed to be the name of a file containing shell commands. If bash isinvoked in this fashion, is set to the name of the file, 
and the positional parameters are set to the remaining arguments, bash reads and executes commands from this file, then 
exits bash's exit status is the exit status of the last command executed in the script. 
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DEFINITIONS 

blank 

word 

name 

meta character 
control operator 


A space or tab. 

A sequence of characters considered as a single unit by the shell. Also known as a token. 

A word consisting only of alphanumeric characters and underscores and beginning with an 
alphabetic character or an underscore. Also referred to as an identifier. 

A character that, when unquoted, separates words. 0 ne of the following: 

(,), <; >, space tab 

A token that performs a control function. It is one of the following symbols: 

||, Sc, Sc Sc,;,(,), |, <mewline> 


RESERVED WORDS 

Reserved words are words that have a special meaning to the shell. The following words are recognized as reserved when 
unquoted and either the first word of a simple command (see "Shell Grammar," next) or the third word of a case or for 
command: 

! case do done elif else esac fi for function if in select then until while { } 


SHELL GRAM MAR 
SIMPLECOMMANDS 

A simple command is a sequence of optional variable assignments followed by words and redirections separated by blank and 
terminated by a control operator. The first word specifies the command to be executed. The remaining words are passed as 
arguments to the invoked command. 

The return value of a simple command is its exit status, or 128 +n if the command is terminated by signal n. 

PIPELINES 

A pipeline is a sequence of one or more commands separated by the character |. The format for a pipeline is 
[! ] c o mma n d [ | command 2 ... ] 

The standard output of command is connected to the standard input of command 2 . This connection is performed before any 
redirections specified by thecommand. (Seethe "Redirection” section, later in this manual page.) 

If the reserved word : precedes a pipeline, the exit status of that pipeline is the logical not of the exit status of the last 
command. Otherwise the status of the pipeline is the exit status of the last command. The shell waits for all commands in 
the pipeline to terminate before returning a value. 

Each command in a pipeline is executed as a separate process (that is, in a subshell). 

LISTS 

A list is a sequence of one or more pipelines separated by one of these operators: or 1 1 , and terminated by one of 

these: or <newline>. 

Of these list operators, && and || have equal precedence, followed by; and&, which have equal precedence. 

If a command is terminated by the control operators., the shell executes the command in the background in a subshell. The 
shell does not wait for thecommand to finish, and the return status is 0 . Commands separated by a; are executed sequen¬ 
tially; the shell waits for each command to terminate in turn. The return status is the exit status of the last command 
executed. 

Thecontrol operators && and 1 1 denoteAND lists and or lists, respectively. An and list has the form: 

command && command2 


c o mma nd 2 is executed if, and only if, command returns an exit status of zero. 
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An or list hastheform 
command command2 

command 2 is executed if, and only if, command returns a non-zero exit status. The return status of and and or lists is the exit 
status of the last command executed i n the list. 

COMPOUND COMMANDS 

A compound command is one of the following: 

(list) 

list isexecuted in a subshell. Variable assignments and built-in commands that affect the shell's environment do not remain 
in effect after the command completes. The return status is the exit status of list. 

{ list ; } 

list is simply executed in the current shell environment. This is known as a group command. The return status is the exit 
status of i i st. 

for name [ in word;] do list ; done 

The list of words following in is expanded, generating a list of items Thevariablenameisset to each element of this list in 
turn, and i i st isexecuted each time. If the in word is omitted, the for command executes i i st once for each positional 
parameter that is set. (See "Parameters," later in thismanual page.) 
select name [ in word;] do list ; done 

The list of words following in is expanded, generating a list of items The set of expanded words is printed on the standard 
error, each preceded by a number. If the in word is omitted, the positional parameters are printed. (See "Parameters.") The 
PS3 prompt is then displayed and a line read from the standard input. If the line consists of the number corresponding to 
one of the displayed words, then the value of name is set to that word. If the line is empty, the words and prompt are 
displayed again. If eof is read, the command completes. Any other value read causes name to beset to null. The line read is 
saved in the variable reply. The list isexecuted after each selection until a break or return command isexecuted. The exit 
status of select is the exit status of the last command executed in list, or zero if no commands were executed, 
case word in [ pattern [ | pattern ] 

A case command fi rst expands word, and tries to match it against each pattern in turn, using the same matching rules as for 
pathname expansion. (See “Path name Expansion,” later in thismanual page.) W hen a match is found, the corresponding list 
isexecuted. After the first match, no subsequent matches are attempted. The exit status is zero if no patterns are matches. 
Otherwise, it is the exit status of the last command executed in i i st. 
if list then list [ elif list then list ] ... [ else list ] fi 

The if list isexecuted. If its exit status is zero, the then list isexecuted. Otherwise, each eiif list isexecuted in turn, and if its 
exit status is zero, the corresponding then list isexecuted and the command completes. Otherwise, the else list isexecuted, if 
present. The exit status istheexit status of the last command executed, or zero if no condition tested True, 
while list do I i st done 

until list do I i st done 

The while command continuously executes the do list as long as the last command in i i st returns an exit status of zero. The 
until command is identical to the while command, except that the test is negated; the do list isexecuted as long as the last 
command in i i st returns a non-zero exit status. The exit status of the while and until commands istheexit status of the last 
do list command executed, or zero if none was executed. 

[ function ] name () { list; } 

This defines a function named name. The body of the function isthe list of commands between {and }. This list isexecuted 
whenever name is specified as the name of a simple command. The exit status of a function istheexit status of the last 
command executed in the body. (See "Functions,” later in thismanual page.) 
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COMMENTS 

In a non interactive shell, or an interactive shell in which the -o interactive-comments option to the set builtin is enabled, a 
word beginning with # causes that word and all remaining characters on that line to be ignored. An interactive shell without 
the -o interactive-comments option enabled doesnot allow comments. 

QUOTING 

Quoting is used to remove the special meaning of certain characters or words to the shell. Quoting can be used to disable 
special treatment for special characters, to pra/ent reserved words from being recognized as such, and to prevent parameter 
expansion. 

Each of the metacharacters listed earlier under "Definitions’’ has special meaning to the shell and must be quoted if it is to 
represent itself. There are three quoting mechanisms: the escape character, single quotes, and double quotes. 

A nonquoted backslash (\) is the escape character. It preserves the literal value of the next character that follows, with the 
exception of <newiine>.lf a \<newiine> pair appears, and the backslash is not quoted, the \<newiine> istreated as a line 
continuation; that is, it iseffectively ignored. 

Enclosing characters in single quotes preserves the literal value of each character with in the quotes. A single quote may not 
occur between single quotes, even when preceded by a backslash. 

Enclosing characters in double quotes preserves the literal value of all characters within the quotes, with theexception of $, \ 
and \. The characters? and 1 retain their special meaning within double quotes. The backslash retains its special meaning 
only when followed by one of the following characters: $, \ \ \, or <newiine>.A double quote may be quoted within double 
quotes by preceding it with a backslash. 

The special parameters* and @ have special meaning when in double quotes. (See "Parameters," next.) 

PARAMETERS 

A parameter isan entity that stores values, somewhat I ike a variable in aconventional programming language. Itcan bea 
name, a number, or one of the special characters listed under "Special Parameters,” following. For the shell's purposes, a 
variable is a parameter denoted by a name 

A parameter is set if it has been assigned a value. The null string is a valid value. Once a variable is set, it may be unset only 
by using the unset built-in command. (See "Shell Built-in Commands,” later in this manual page.) 

A variable may be assigned to by a statement of the form: 

n a me = [ v a I u e ] 

If vai ue is not given, the variable is assigned the null string. All values undergo tilde expansion, parameter and variable 
expansion, command substitution, arithmetic expansion, and quote removal. If the variable has its-i attribute set (see 
declare in "Shell Built-in Commands") then value is subject to arithmetic expansion even if the $[...] syntax does not 
appear. W ord splitting is not performed, with theexception of ■$(?", as explained under "Special Parameters.” Pathname 
expansion is not performed. 

POSITIONAL PARAMETERS 

A positional parameter is a parameter denoted by one or more digits, other than the single digit 0. Positional parameters are 
assigned from the shell's arguments when itisinvoked, and may be reassigned using theset built-in command. Positional 
parameters may not be assigned to with assignment statements. The positional parameters are temporarily replaced when a 
shell function is executed. (See "Functions," later in this manual page.) 

When a positional parameter consisting of more than a single digit is expanded, it must be enclosed in braces. (See 
"Expansion," later in thismanual page.) 

SPECIAL PARAMETERS 

The shell treats several parameters specially. These parameters may only be referenced; assignment to them is not allowed. 
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* Expands to the positional parameters, starting from one. When theexpansion occurswithin double 
quotes, it expands to a singleword with the value of each parameter separated by the first character 
oftheiFs special variable. That is, "$*“ is equivalent to "$ic$ 2 c. where c isthefirst character of 
the value of the ifs variable If ifs is null or unset, the parameters are separated by spaces. 

@ Expands to thepositional parameters, startingfrom one. When theexpansion occurswithin double 

quotes, each parameter expands as a separate word. That is, "$@" is equivalent to "$r Mi $ 2 " .... 
When there are no positional parameters, “ir and $@ expand to nothing (in otherwords, they are 
removed). 

# Expands to the number of positional parameters in decimal. 

? Expands to the status of the most recently executed foreground pipeline. 

Expands to the current option flags as specified upon invocation, bytheset built-in command, or 
those set by the shell itself (such as the -i flag). 

$ Expands to the process ID of the shell. In a o subshell, it expandsto theprocess ID ofthecurrent 

shell, not the subshell. 

i Expands to the process ID of the most recently executed background (asynchronous) command. 

0 Expandsto the name of the shell or shell script. Thisisset at shell initialization. I f bash isinvoked 

with a file of commands, is set to the name of that file. If bash is started with the -c option, then is 
set to thefirst argument after the string to be executed, if one is present. Otherwise, it is set to the 
pathname used to invoke bash, as given by argument zero. 

Expandsto the last argument to the previous command, after expansion. Also set to the full 
pathnameof each command executed and placed in the environment exported to that command. 


SHELL VARIABLES 


T he following variables are set by the shell: 


PPID 

PWD 

OLDPWD 

REPLY 

UID 

EUID 

BASH 

BASH_VERSION 

SHLVL 

RANDOM 


SECONDS 


LINENO 


The process ID of the shell's parent. 

Thecurrent working directory asset bythecd command. 

Thepreviousworking directory asset by thecd command. 

Set to the line of input read by the read built-in command when no arguments are 
supplied. 

Expandsto the user ID of thecurrent user, initialized at shell startup. 

Expandsto the effective user ID ofthecurrent user, initialized at shell startup. 

E xpan ds to th e fu 11 path n ame u sed to i n vo ke th i s i n stan ce of bas h . 

Expandsto theversion number of this instanceof bash. 

Incremented by oneeach time an instanceof bash is started. 

Each time this parameter isreferenced, a random integer is generated. The sequence 
of random numbers may be initialized by assigning a value to random. If random is 
unset, it loses its special properties, even if it is subsequently reset. 

Each time this parameter isreferenced, the number of seconds since shell invocation 
is returned. If a value is assigned to seconds, the value returned upon subsequent 
references is the number of seconds si nee the assignment plus the value assigned. If 
seconds is unset, it loses its special properties, a/en if it is subsequently reset. 

Each timethisparameter isreferenced, theshell substitutes a decimal number 
representing thecurrent sequential line number (starting with 1) within a script or 
function. W hen notin a script or function, the value substituted is not guaranteed to 
be meaningful. When in afunction, the value is not the number of the source line 
that the command appears on (that information has been lost by the time the 
function isexecuted), butisan approximation ofthenumber of simple commands 
executed in the current function. If lineno is unset, it loses its special properties, even 
if it is subsequently reset. 
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HISTCMD 

T he history number, or index in the history list, of the current command. If histcmd 
is unset, it loses its special properties, even if it is subsequently reset. 

OPTARG 

Thevalueof the last option argument processed bythegetopts built-in command. 
(See"Shell Built-in Commands," later in thismanual page). 

OPTIND 

The index of the next argument to be processed bythegetopts built-in command. 
(See"Shell Built-in Commands.") 

HOSTTYPE 

Automatically set to a string that uniquely describes the type of machine on which 
bash is executing. The default is system-dependent. 

OSTYPE 

Automatically set to a string that describes the operating system on which bash is 
executing. T he default is system-dependent. 

T he following variables are used by the shell. In some cases, bash assigns a default value to avariable; these cases are noted in 
thefollowing list: 

IFS 

The internal field separator that is used for word splitting after expansion and to split 
lines into words with the read built-in command. The default value is 
<space><tab><newline>. 

PATH 

Thesearch path for commands. It is a col on-separated list of directoriesin which the 
shell looks for commands. (See "Command Execution," later in thismanual page). 

T he default path is system-dependent, and is set by the administrator who installs 
bash. A Common value is /usr/gnu/bin: /usr/ local /bin: /usr/ucb: / bin: / usr/bin:. 

HOME 

T he home di rectory of the current user; the default argument for the cd built-in 
command. 

CDPATH 

Thesearch path for the cd command. This is a colon-separated list of directoriesin 
which the shell looks for destination directories specified bythecd command. A 
samplevalueis .:':/usr. 

ENV 

If this parameter is set when bash is executing a shell script, its value is interpreted as 
a filename containing commands to initialize the shell, as in .bashrc. Thevalueof 
env is subjected to parameter expansion, command substitution, and arithmetic 
expansion before being interpreted as a pathname, path is not used to search for the 
resultant pathname. 

MAIL 

If this parameter is set to a filename and the mailpath variable is not set, bash informs 
theuser of the arrival of mail in thespecified file. 

MAILCHECK 

Specifies how often (in seconds) bash checks for mail. The default is 60 seconds. 
When it is time to check for mail, the shell does so before prompting. If this variable 
is unset, theshell disables mail checking. 

MAILPATH 

A colon-separated list of pathnames to be checked for mail. The message to be 
printed may be specified by separating the path name from the message with a 
question mark (?). $ stands for the name of the current mailfile. 

Example: 

MAILPATH\ 

='/usr/spool/mail/bfox?"You have 
mail": "/shell-mail?"$_has mail! 111 

bash supplies a default valuefor this variable but the location of theuser mail files 
that it uses issystem-dependent (for example, /usr/spooi/maii/$usER). 

MAIL_WARNING 

If set, and a file that bash is checking for mail has been accessed since the last time it 
was checked, the message "The mail in mail-file has been read" isprinted. 

PS1 

The value of this parameter is expanded (see "Prompting," later in thismanual page) 
and used as the primary prompt string. The default value isbash\$. 

PS2 

Thevalueof this parameter isexpanded and used as the secondary prompt string. 

T he default is>. 
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PS4 


HISTSIZE 

HISTFILE 


HISTFILESIZE 


OPTERR 


PROMPT_COMMAND 

IGNOREEOF 


TMOUT 


FCEDIT 

FIGNORE 


INPUTRC 


notify 


history_control HISTCONTROL 


command_oriented_history 
glob_dot_filenames 
allow-null_glob_expansion 
histchars 


Thevalueofthisparameterisused as the prompt for the select command. (See 
"Shell Grammar,” earlier in this manual page.) 

The value of this parameter isexpanded and thevalueisprinted before each 
command bash displays during an execution trace. The first character of ps4 is 
replicated multi pie times, as necessary, to indicate multiple levels of indirection. The 
default is+. 

The number of commands to remember in the command history, (See"H istory," 
later in this manual page.) The default value is 500 . 

The name of thefilein which command history is saved. (See"H istory.") The 
default value is '/.bash_histony. If unset, the command history is not saved when an 
interactive shell exits. 

The maximum number of lines contained in the history file When this variable is 
assigned a value, the history file is truncated, if necessary, to contain no more than 
that number of lines. T he default value is 500 . 

If set to the value 1 , bash displays error messages generated by thegetopts built-in 
command. (See "Shell Built-in Commands.”), opterr isinitialized to 1 each time the 
shell is invoked or a shell script is executed. 

If set, the value is executed as a command prior to issuing each primary prompt. 
Controls the action of the shell on receipt of an eof character as the sole input. If set, 
the value is the number of consecutive eof characters typed as the first characters on 
an input line before bash exits If the variable exists but does not have a numeric 
value, or has no value, the default value is 10 . If it does not exist, eof signifies the end 
of input to the shell. This is only in effect for interactive shells. 

If set to a value greater than zero, the value is interpreted as the number of seconds 
to wait for input after issuing the primary prompt, bash terminates after waiting for 
that number of secondsif input does not arrive. 

T he default editor for the tc built-in command. 

A colon-separated list of suffixes to ignore when performing filename completion. 
(See "Readline" later in this manual page.) A filename whose suffix matches one of 
theentriesin fignore isexcluded from the list of matched filenames. A samplevalue 
is .or. 

Thefilenameforthereadiine startup file, overriding the default of '/.input™. (See 
"Readline.") 

If set, bash reports terminated background jobs immediately, rather than waiting 
until before printing the next primary prompt. (See also the -b option to the set 
built-in command.) 

If set to a value of ignonespace, lines that begin with a space character are not entered 
on the history list. If set to a value of ignoredups, lines matching the last history line 
are not entered. A value of ignoreboth combines the two options. If unset, or if set to 
any other value than the preceding, all lines read by the parser are saved on the 
history list. 

If set, bash attempts to save all lines of a multi pie- line command in the same history 
entry. T his allows easy reediting of multiline commands. 

If set, bash includes filenames beginning with a period (.) in the results of pathname 
expansion. 

If set, bash allows pathname patterns which match no files (see "Pathname 
Expansion") to expand to a null string, rather than themselves. 

The two or three characters that control history expansion and tokenization. (See 
"H istory Expansion," later in thismanual page.) The first character isthe history 
expansion character; that is, the character that signals the start of a history expansion, 
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normally 1 . The second character is the quick substitution character, which is used as 
shorthand for rerunning the previous command entered, substituting onestring for 
another in the command. The default is". The optional third character isthe 
character that signifies that the remainder of the line is a comment, when found as 
the first character of a word, normally #. The history comment character causes 
history substitution to be skipped fortheremainingwordson theline. It does not 
necessarily cause the shell parser to treat the rest of the line as a comment. 

noiinks If set, the shell does not follow symbolic links when executing commands that 

change the current working directory. It uses the physical directory structure instead. 
By default, bash follows the logical chain of directories when performing commands 
that change the current directory, such ascd. See also the description of the-p 
option to theset builtin ("Shell Built-in Commands"). 

hostname_compietion_fiie hostfile C ontainsthe name of a file in the same format as /etc/hosts that should be read 

when the shell needs to complete a hostname. Thefile may be changed interactively; 
the next time hostname completion isattempted bash adds the contents of the new 
fiIe to the already existing database. 

nociobber If set, bash does not overwrite an existing file with the >, >&, and <> redirection 

operators. This variable may be overridden when creating output files by using the 
redirection operator >| instead of >. (Seealso the-c option to theset built-in 
command.) 

auto_resume This vari abl e control s h ow the shell interacts with the user and job control. Ifthis 

variable is set, single word simple commandswithout redirections are treated as 
candidates for resumption of an existing stopped job. There is no ambiguity allowed; 
if there is more than onejob beginningwith the string typed, thejob most recently 
accessed isselected. The name of a stopped job, in this context, isthecommand line 
used to start it. If set to the value exact, thestring supplied must match thenameof 
a stopped job exactly; if set to substring, thestring supplied needsto match a 
substri ng of the name of a stopped job. T he substring value provides functionality 
analogous to the %? job ID. (See "Job Control," later in this manual page.) If set to 
any other value, the supplied string must be a prefix of a stopped job's name; this 
provides functionality analogousto the% job id. 

no_exit_on_faiied_exec If this variable exists, a non interactive shell will not exit if it cannot executethefile 

specified in theexec built-in command. An interactive shell does not exit if exec 
fails. 

cdabie_vars If this is set, an argument to the cd built-in command that is not a directory is 

assumed to be the name of a variable whose value is the directory to change to. 


EXPANSION 

Expansion is performed on thecommand line after it has been split into words. There are seven kinds of expansion 
performed: brace expansion, tilde expansion, parameter and variable expansion, command substitution, arithmetic expan¬ 
sion, word splitting, and pathname expansion. 

The order of expansions is as follows: brace expansion, tilde expansion, parameter, variable, command, and arithmetic 
substitution (donein a left-to-rightfashion), word splitting, and pathnameexpansion. 

On systems that can support it, there isan additional expansion available: process substitution. 

Only brace expansion, word splitting, and pathnameexpansion can change the number of words of the expansion; other 
expansions expand a single word to a single word. The single exception to this isthe expansion of n $@", as explained earlier. 
(See "Parameters.”) 
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BRACE EXPANSION 

Brace expansion is a mechanism by which arbitrary strings may be generated. This mechanism issimilar to pathname 
expansion, but thefilenames generated need not exist. Patterns to be brace expanded taketheform of an optional preamble, 
followed by a series of comma-separated strings between a pair of braces, followed by an optional postamble. The preamble is 
prepended to each string contained within the braces, and the postamble isthen appended to each resulting string, 
expanding left to right. 

Brace expansions may be nested. The results of each expanded string are not sorted; left to right order is preserved. For 
example, a{d,c,b}e expands into ade ace abe. 

Brace expansion is performed before any other expansions, and any characters special to other expansions are preserved in the 
result. It is strictly textual, bash does not apply any syntactic interpretation to the context of the expansion or the text 
between the braces. 

A correctly formed brace expansion must contain unquoted opening and closing braces, and at least one unquoted comma. 
Any incorrectly formed brace expansion is left unchanged. 

This construct is typically used as shorthand when the common prefix of the strings to be generated is longer than in the 
preceding example such as 

mkdin /usr/local/src/bash/{old,new,dist,bugs} 
or 

chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}} 

Brace expansion introduces a slight incompatibility with traditional versions of sh, the Bourne shell, sh does not treat 
opening or closing braces specially when they appear as part of a word, and preserves them in the output, bash removes 
braces from words as a consequence of brace expansion. For example, a word entered to sh asfiie{i, 2 > appears identically in 
the output. The same word is output asttiei fiie 2 after expansion by bash. If strict compatibility with sh is desired, start 
bash with the-nobraceexpansion flag (9se "0 ptions," earlier in thismanual page) or disable brace expansion with the+o 
braceexpand option totheset command. (See"Shell Built-in Commands.'') 

TILDE EXPANSION 

If a word begins with a tilde character (), all of the characters preceding the first si ash (or all characters, if there is no slash) 
are treated as a possible login name. If thislogin nameisthenull string, the tilde is replaced with thevalue of the parameter 
home. If home isunset, the home di rectory oftheuser executing theshell is substituted instead. 

If a + follows the tilde thevalueof pwd replaces the tilde and + If a- follows, the value of oldpwd is substituted. I f the value 
following the ti Ide is a valid login name, thetildeand login name are replaced with the home directory associated with that 
name. If the name is invalid, or the tilde expansion fails, theword isunchanged. 

Each variable assignment is checked for unquoted instances of ti Ides following a : or =. In thesecases, tilde substitution is 
also performed. Consequently, one may use pathnames with tildesin assignments to path, mailpath, and cdpath, and theshell 
assigns the expanded value. 

PARAMETER EXPANSION 

T he $ character introduces parameter expansion, command substitution, or arithmetic expansion. The parameter name or 
symbol to be expanded may be enclosed in braces, which are optional but serve to protect the variable to be expanded from 
characters immediately following it which could be interpreted as part of the name. 

${pa r a met e r } T he value of pa r a met e r is substituted. T he braces are required when parameter is a positional parameter 

with more than onedigit, or when parameter isfollowed by a character that is not to be i nterpreted as part 
of its name. 


In each of the following cases, word is subject to tilde expansion, parameter expansion, command substitution, and arithmetic 
expansion, bash tests for a parameter that isunset or null; omitting the colon results in a test only for a parameter that is 
unset. 
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${par amet er :-wor d} 
${par amet er : =wor d} 

${par amet er :?wor d} 

${par amet er :+wor d} 

${#par a meter} 

${par amet er #wor d} 
${par amet er ##wor d} 

${par amet er %wor d} 
${par amet er %%wor d} 


Use default values. If parameter is unset or null, theexpansion of word is substituted. Otherwise, the 
valueof parameter is substituted. 

Assign default values. If parameter is unset or null, theexpansion of word is assigned to parameter. 
Thevalueof parameter isthen substituted. Positional parameters and special parameters may not be 
assigned to in thisway. 

D isplay Error if null or unset. If parameter is null or unset, theexpansion of word (ora message to 
that effect if word is not present) is written to the standard error and the shell, if it is not interactive, 
exits. Otherwise, thevalueof parameter is substituted. 

Use Alternate Value. If parameter is null or unset, nothing is substituted; otherwise, theexpansion 
Of word is substituted. 

The length in characters of thevalueof par a meter is substituted. If parameter is* or @, the length 
substituted isthe length of * expanded within double quotes. 

The word is expanded to produce a pattern just as in pathname expansion. If the pattern matches 
the beginning of thevalueof parameter, then theexpansion is the value of pa r a met er with the 
shortest matching pattern deleted (the# case) or the longest matching pattern deleted (the## case). 
Theword isexpandedto producea pattern just as in pathname expansion. Ifthe pattern matchesa 
trailing portion of thevalueof parameter , then theexpansion is the value of parameter with the 
shortest matching pattern deleted (the% case) or the longest matching pattern deleted (the %% case). 


COMMAND SUBSTITUTION 

Command substitution allows the output of a command to replace the command name. 

There are two forms: 

$ (command ) 

or 

' c o mma n d' 

performs the expansion by executing command and replacing the command substitution with the standard output of the 
command, with any trailing newlines deleted. 

When the old-style backquote form of substitution is used, backslash retains its literal meaning except when followed by$, \ 
or \. When usi ng the $ (command ) form, all characters between the parentheses make up the command; none are treated 
specially. 

Command substitutions may be nested. To nest when using the old form, escape the inner backquoteswith backslashes. 

If the substitution appears within double quotes, word splitting and pathname expansion are not performed on the results. 

ARITHMETIC EXPANSION 

Arithmetic expansion allows the evaluation of an arithmetic expression and the substitution of the result. There are two 
formats for arithmetic expansion: 

$[expression] 

$((expression)) 

The expression is treated as if it were within double quotes, but a double quote inside the braces or parentheses is not treated 
specially. All tokens in the expression undergo parameter expansion, command substitution, and quote removal. Arithmetic 
substitutions may be nested. 

The evaluation is performed according to the rules listed under "Arithmetic Evaluation," later in this section. If express i on is 
invalid, bash prints a message indicating failure and no substitution occurs. 

PROCESS SUBSTITUTION 

Process substitution is supported on systems that support named pipes (FIFOs) or the /dev/td method of naming open files. 
It takes the form of <(i i st > or >(i i st ). The process list is run with its input or output connected to a FIFO or some file in / 
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dev/fd. The name of this file is passed as an argument to the current command as the result of the expan si on. If the >(i i st ) 
form is used, writing to the file will provide input for list. If the<(i i st ) form is used, the file passed as an argument should 
be read to obtain the output of list. 

On systemsthat support it, process substitution is performed simultaneously with parameter and variable expansion, 
command substitution, and arithmetic expansion. 

WORD SPLITTING 

The shell scans the results of parameter expansion, command substitution, and arithmetic expansion that did not occur 
within double quotes for word splitting. 

The shell treats each character of ifs as a delimiter, and splits the results of the other expansions into words on these 
characters. If the value of ifs isexactly <space><tab><newiine>, the default, then any sequence of ifs characters serves to 
delimit words. If ifs has a value other than the default, then sequences of the whitespace characters space and tab are ignored 
at the beginning and end of the word, as long as the whitespace character is in the value of ifs (an ifs whitespace character). 
Any character in ifs that is not ifs whitespace, along with any adjacent ifs whitespace characters, delimits a field. A 
sequence of ifs whitespace characters is also treated as a delimiter. If the value of ifs is null, no word splitting occurs ifs 
cannot be unset. 

Explicit null arguments (" 11 or ") are retained. Implicit null arguments, resulting from the expansion of parameters that have 
no values, are removed. 

N otethat if no expansion occurs no splitting is performed. 

PATHNAME EXPANSION 

Afterword splitting, unless the -f option has been set, bash scans each word for the characters *, ?, and [. If one of these 
characters appears, then the word is regarded as a pattern and replaced with an alphabetically sorted list of pathnames 
matching the pattern. If no matching pathnames are found, and the shell variable aiiow_nuii_giob_expansion is unset, the 
word is left unchanged. If the variable is set, and no matches are found, the word is removed. When a pattern is used for 
pathname generation, the character (.) at the start of a name or immediately following a slash must be matched explicitly, 
unless the shell variable giob_dot_tiienames is set. The slash character must always be matched explicitly. In other cases, the 
(.) character i s not treated speci al ly. 

T he special pattern characters have the followi ng meanings: 

* M atches any string, including the null string. 

? M atches any single character. 

[...] M atches any one of the enclosed characters. A pair of characters separated by a minus sign denotes a range; 

any character lexically between those two characters, inclusive, is matched. If thefirst character following 
the [ is a ! or a \ then any character not enclosed is matched. A - or ] may be matched by including it as 
thefirst or last character in the set. 

QUOTE REMOVAL 

After the preceding expansions all unquoted occurrences of the characters!, 1 , and ■ are removed. 

REDIRECTION 

Before a command is executed, its input and output may be redirected using a special notation interpreted by the shell. 
Redirection may also be used to open and close files for the current shell execution environment. The following redirection 
operatorsmay precede or appear anywhere within a simple command ormay follow a command. Redirectionsare processed 
in the order they appear, from left to right. 

In the foil owing descriptions if the file descriptor number is omitted, and thefirst character of the redirection operator is<, 
the redirection refers to the standard input (file descriptor 0 ). If thefirst character of the redirection operator is>, the 
redirection refers to the standard output (file descriptor 1). 
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The word that follows the redirection operator in the foil owing descriptions is subjected to brace expansion, tilde expansion, 
parameter expansion, command substitution, arithmetic expansion, quote removal, and pathname expansion. If it expands to 
more than oneword, bash reports an error. 

N otethat the order of redirections is significant. For example the command: 

Is > di r I i st 2>&1 

directs both standard output and standard error to the file di r i i st , while the command 
Is 2>&1 > di rIi st 

directs only the standard output to filedi ri i st , because the standard error was duplicated as standard output before the 
standard output was redirected to dirlist. 

REDIRECTING INPUT 

Redirection of input causes the file whose name results from the expansion of word to be opened for reading on file 
descriptor n, orthestandard input (file descriptor 0) if n is not specified. 

The general format for redirecting input is 

[ n ] <wo r d 

REDIRECTING OUTPUT 

Redirection of output causes the file whose name results from the expansion of word to be opened for writing on file 
descriptor n, orthestandard output (file descriptor 1) if n is not specified. If the file does not exist, it is created; if it does 
exist it istruncated to zero size. 

Thegeneral format for redirecting output is 

[ n ] >wo r d 

If the redirection operator is>|, then the value of the -c option to the set built-in command is not tested, and file creation is 
attempted. (See also the description of nociobber under "Shell Variables," earlier in this manual page.) 

APPENDING REDIRECTED OUTPUT 

Redirection of output in this fashion causes the file whose name results from the expansion of word to be opened for 
appending on file descriptor n, orthestandard output (file descriptor 1) if n is not specified. If the file does not exist, it is 
created. 

Thegeneral format for appending output is 

[n ]»wor d 

REDIRECTING STANDARD OUTPUTAND STANDARD ERROR 

bash allows both the standard output (file descriptor 1) and the standard error output (file descriptor 2) to be redirected to 
thefilewhosenameistheexpansion of word with this construct. 

There are two formats for redirecting standard output and standard error: 

&>wo r d 

and 

>&wo r d 

Of the two forms, the first is preferred. This is semantically equivalent to 

>word 2>&1 

HERE-DOCUMENTS 

This type of redirection instructs the shell to read input from the current source until a line containing only word (with no 
trailing blanks) is seen. All of the lines read up to that point are then used as the standard input for a command. 
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The format of here-documents is as follows: 

«[-]word her e- doc ument delimiter 

N o parameter expansion, command substitution, pathname expansion, or arithmetic expansion is performed on word. If any 
characters in word are quoted, the del i mi ter is the result of quote removal on word, and the lines in the here- document are not 
expanded. Otherwise, all lines of thehere - document are subjected to parameter expansion, command substitution, and 
arithmetic expansion. In the latter case, the pair \<newiine> is ignored, and \ must be used to quote the characters \, $, and '. 

If the redirection operator is«-, then all leading tab characters are stripped from input lines and the line containing 
delimiter. This allows here-documents within shell scripts to be indented in a natural fashion. 

DUPLICATING FILE DESCRIPTORS 

The redirection operator: 

[n ]<&wor d 

is used to duplicate input file descriptors. If word expands to one or more digits, the file descriptor denoted by n is made to be 
a copy of that file descriptor. If word evaluates to -, file descriptor n isclosed. If n is not specified, the standard input (file 
descriptor 0) isused. 

The operator: 

[n ]>&wor d 

isused similarly to duplicate output file descriptors If n is not specified, the standard output (file descriptor 1) isused. Asa 
special case, if n is omitted, and word does not expand to one or more digits, the standard output and standard error are 
redirected as described previously. 

OPENING FILE DESCRIPTORS FOR READING AND WRITING 

The redirection operator: 

[n]<>wor d 

causes the file whose name is the expansion of word to be opened for both reading and writing on fi le descriptor n, or as the 
standard input and standard output if n is not specified. If the file does not exist, itiscreated. 

FUNCTIONS 

A shell function, defined as descri bed above under "Shell Grammar,” stores a series of commands for later execution. 
Functions are executed in the context of the current shell; no new process is created to interpret them (contrast this with the 
execution of a shell script). W hen a function is executed, the arguments to the function become the positional parameters 
during its execution. The special parameter# is updated to reflect the change. Positional parameter 0 is unchanged. 

Variables local to the function may be declared with the local built-in command. Ordinarily, variables and their values are 
shared between the function and its caller. 

If the built-in command return isexecuted in afunction, thefunction completes and execution resumes with thenext 
command after thefunction call. When afunction completes, the values of the positional parameters and the special 
parameter# are restored to the values they had prior to function execution. 

Function names may be listed with the-f option to the declare or typeset built-in commands. Functions may be exported 
so that subshells automatically have them defined with the-f option to the export builtin. 

Functions may be recursive. N 0 limit is imposed on the number of recursive calls. 

ALIASES 

The shell maintains a list of aliases that may beset and unset with the alias and unaiias built-in commands. (See "Shell 
Built-in Commands"). The first word of each command, if unquoted, is checked to see if it has an alias. If so, that word is 
replaced by the text of the alias. The alias name and the replacement text may contain any valid shell input, including the 
meta characters listed above, with the exception that the alias name may not contain =. The first word of the replacement text 
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is tested for aliases, but a word that is identical to an alias being expanded is not expanded a second time. This means that 
one may alias is to is -f, for instance, and bash does not try to recursively expand the replacement text. If the last character 
of the alias value is a blank, then the next command word following the alias is also checked for alias expansion. 

Aliases are created and listed with the alias command, and removed with theunaiias command. 

There is no mechanism for using arguments in the replacement text, as in csh. If arguments are needed, a shell function 
should be used. 

Aliases are not expanded when the shell isnot interactive. 

The rules concerning the definition and use of aliases are somewhat confusing, bash always reads at least one complete line of 
input before executing any of the commands on that line. Aliases are expanded when a command is read, not when it is 
executed. Therefore, an alias definition appearing on the same line as another command does not take effect until the next 
line of input is read. This means that the commands following the alias definition on that line are not affected by the new 
alias. This behavior isalso an issuewhen functions are executed. Aliases are expanded when the function definition isread, 
not when thefunction is executed, because a function definition is itself a compound command. As a consequence, aliases 
defined in a function are not avail able until after that function is executed. T o be safe always put alias definitions on a 
separate line, and do not usealiasin compound commands. 

Note that for almost every purpose, aliases are superseded by shell functions. 

JOB CONTROL 

Job control refers to the ability to selectively stop (suspend) the execution of processes and continue (resume) their execution 
at a later point. A user typically employs this facility via an interactive interface supplied jointly by the system's terminal 
driver and bash. 

The shell associates a job with each pipeline. It keeps a table of currently executing jobs, which may be listed with the jobs 
command. W hen bash starts a job asynchronously (in the background), it prints a line that looks like this: 

[ 1 ] 25647 

indicating that this job is job number 1 and that the process ID of the last process in the pipeline associated with this job is 
25647 . All of the processes in a single pipeline are members of the same job. bash uses the job abstraction as the basis for job 
control. 

T o facilitate the implementation of the user interface to job control, the system maintains the notion of a current terminal 
process group ID. M embers of this process group (processes whose process group ID is equal to the current terminal process 
group ID) receive keyboard-generated signals such as sigint. These processes are said to be in the foreground. Background 
processes are those whose process group ID differs from the terminal's; such processes are immune to keyboard-generated 
signals. 0 nly foreground processes are allowed to read from or write to the terminal. Background processes that attempt to 
read from (write to) the terminal are sent asiGuiN (sigttou) signal by the terminal driver, which, unless caught, suspends 
the process. 

If the operating system on which bash is running supports job control, bash allows you to use it. T yping the suspend 
character (typically 'z, control-z) while a process is running causes that process to be stopped and returns you to bash. 
Typing the delayed suspend character (typically "y, control -y) causes the process to be stopped when it attempts to read 
input from the terminal, and control to be returned to bash. You may then manipulate the state of this job, using the bg 
command to continue it in the background, thetg command to continue it in the foreground, or the kill command to kill 
it. A Ctrl+Z takes effect immediately, and has the additional side effect of causing pending output and typeahead to be 
discarded. 

There are a number of ways to refer to a job in the shell. T he character % introduces a job name. Job number n may be 
referred to as%n. A job may also be referred to using a prefix of the name used to start it, or using a substring that appears in 
its command line. For example %ce refers to a stopped ce job. If a prefix matches more than one job, bash reports an error. 
Using%?ce, on the other hand, refers to any job containing thestring ce in its command line. If the substring matches more 
than one job, bash reports an error. The symbols%% and %+ refer to the shell's notion of the current job, which is the last job 
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stopped while it was in the foreground. The previous job may dereferenced usi ng %-.l n output pertaining to jobs (for 
example, theoutput of the j obs command), the current job is always flagged with a+, and the previous job with a-. 

Simply naming a job can be used to bring it into the foreground: %i is a synonym for fg %i, bringing job 1 from the 
background into the foreground. Similarly, %i & resumesjob 1 in the background, equivalent to bg %i. 

T he shell learns i mmediately whenever a job changes state. N orm ally, bash waits until it is about to print a prompt before 
reporting changes in ajob's status so as to not interrupt any other output. If the -b option to the set built-in command is set, 
bash reports such changes immediately. (See also the description of the notify variable in "Shell Variables,'' earlier in this 
manual page.) 

If you attempt to exit bash while jobs are stopped, the shell prints a message warning you. You may then use the jobs 
command to inspect their status. If you do this, or try to exit again immediately, you are not warned again, and the stopped 
jobs are terminated. 

SIGNALS 

When bash is interactive it ignores sigterm (so that kin 0 does not kill an interactive shell), and sigint is caught and 
handled (so that the wait built-in is interruptible). In all cases, bash ignores sigquit. If job control isin effect, bash ignores 

SIGTTIN, SIGTTOU, and SIGTSTP. 

Synchronous jobs started by bash have signals set to the values inherited by the shell from its parent. When job control isnot 
in effect, background jobs (jobs started with &) ignore sigint and sigquit. Commands run as a result of command substitu¬ 
tion ignore the keyboard-generated job control signals sigttin, sigttou, and sigtstp. 

COMMAND EXECUTION 

After a command has been split into words, if it results in a simple command and an optional list of arguments, the 
following actionsare taken. 

If the command name contains no slashes, the shell attempts to locate it. If there exists a shell function by that name, that 
function is invoked as described earlier in "Functions." If the name does not match a function, the shell searches for it in the 
list of shell builtins. If a match isfound, that builtin is invoked. 

If the name is neither a shell function nor a builtin, and contains no slashes, bash searches each element of the path for a 
directory containing an executablefile by that name. If the search is unsuccessful, the shell prints an error message and 
returns a nonzero exit status. 

If the search is successful, or if the command name contains one or more slashes, the shell executes the named program. 
Argument 0 is set to the name given, and the remaining arguments to the command are set to the arguments given, if any. 

If this execution fails because the file is not in executable format, and the file is not a directory, it is assumed to be a shell 
script, a file containing shell commands. A subshell is spawned to execute it. This subshell reinitializes itself, so that the effect 
is as if a new shell had been invoked to handle the script, with the exception that the locations of commands remembered by 
the parent (see hash under "Shell Built-in Commands") are retained by the chi Id. 

If the program is a file beginning with #!, the remainder of the first line specifies an interpreter for the program. The shell 
executes the specified interpreter on operating systems that do not handle this executable format themselves. The arguments 
to the interpreter consist of a single optional argument following the interpreter name on the first line of the program, 
followed by the name of the program, followed by the command arguments, if any. 

ENVIRONMENT 

When a program is invoked, it is given an array of strings called the environment. This is a list of nam Rvalue pairs, of the 
form name=value. 

T he shell allows you to manipulate the environment in sa/eral ways. On invocation, the shell scansitsown environment and 
creates a parameter for each name found, automatically marking it for export to child processes. Executed commands inherit 
the environment. The export and declare -x commands allow parameters and functions to be added to and deleted from the 
environment. If the value of a parameter in the environment is modified, the new value becomes part of the environment, 
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replacing the old. The environment inherited by any executed command consists of the shell's initial environment, whose 
values may be modified in the shell, less any pairs removed by the unset command, plus any additions via the export and 
declare-x commands. 

The environment for any simple command or function may be augmented temporarily by prefixing it with parameter 
assignments, as described earlier in "Parameters." These assignment statements affect only the environment seen by that 
command. 

If the -k flag is set (seethe set built-in command), then all parameter assignments are placed in the environment for a 
command, not just those that precede thecommand name. 

When bash invokes an external command, the variable is set to the full path name of thecommand and passed to that 
command in its environment. 

EXIT STATUS 

For the purposes of the shell, a command which exits with a zero exit status has succeeded. An exit status of zero indicates 
success. A non-zero exit status indicates failure. When a command terminates on a fatal signal, bash uses the value of 
128+signai as the exit status. 

If a command is not found, the chi Id process created to execute it returns a status of 127. If a command is found but is not 
executable, the return status is 126. 

bash itself returns the exit status of the last command executed, unless a syntax error occurs, in which case it exits with a non¬ 
zero value. (See also the exit built-in command.) 

PROMPTING 

When executing interactively, bash displays the primary prompt psi when it is ready to read a command, and the secondary 
prompt ps2 when it needs more input to complete a command, bash allows these prompt strings to be customized by 
inserting a number of backslash-escaped special characters that are decoded as follows: 

\t Thecurrenttimein hh: hm: ss format 

\d The date in "Weekday M onth Date" format (for example, "T ueM ay 26 ") 

\n Newline 

\s The name of the shell, thebasenameof $0 (the portion following the final slash) 

\w Thecurrentworkingdirectory 

\w The basename of the current worki ng di rectory 

\u The username of the current user 

\h The hostname 

\# Thecommand number of thiscommand 

\i The history number of this command 

\$ If the effecti ve UID is 0, a#, otherwise a $ 

\nnn T he character correspondi ng to the octal number nnn 

\\ A backslash 

\[ Begin a sequence of nonprinting characters, which could be used to embed a terminal control sequence 

into the prompt 

\] End a sequence of nonprinting characters 

T he command number and the history number are usually different: the history number of a command is its position in the 
history list, which may include commands restored from the history file (see “H i story," later in this manual page), while the 
command number is the position in the sequence of commands executed during the current shell session. After the string is 
decoded, it is expanded via parameter expansion, command substitution, arithmetic expansion, and word splitting. 
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READ LINE 

T his isthe library that handles reading input when using an interactive shell, unless the -nolineediting option isgiven. By 
default, the line editing commands are similar to those of emacs. A vi-style line editing interface is also available. 

In this section, theemacs-style notation is used to denote keystrokes. Control keys are denoted by c-key; for example, c-n 
means Ctrl-N. Similarly, meta keys are denoted by M-key, so m-x means Meta-x. (On keyboards without a meta key, m-x 
means Esc-X; that is, press the Escape key, then theX key. This makes ESC the meta prefix. The combination m-c-x means 
Esc-Control-x, or press the Escape key then hold the Control key while pressing the X key.) 

The default key-bindings may be changed with a / .inputrc file. The value of the shell variable inputrc, if set, is used instead 
of '/.inputrc. Other programs that use this library may add their own commands and bindings. 

For example, placing 
M-Control-u: uni versal-argument 

or 

C-Meta-u: u n i v e r s a I - a r g u me n t 

into the / .inputrc would makeM-c-u execute the readiine command uni versal-argument.T he following symbolic character 
names are recognized: rubout, del, esc, lfd, newline, ret, return, spc, space, and tab. In addition to command names, 
readiine allowskeysto be bound to a string that is inserted when the key is pressed (a macro). 

Readline is customized by putting commands in an initialization file The name of this file is taken from the value of the 
inputrc variable. If that variable is unset, the default is '/.inputrc. When a program that uses the readiine library starts up, 
theinit file is read, and the key bindings and variables are set. There are only a few basic constructs allowed in the readiine 
init file. Blank lines are ignored. Lines beginning with a# are comments Lines beginning with a$ indicate conditional 
constructs. Other lines denote key bindings and variable settings. 

The syntax for controlling key bindings in the '/.inputrc file is simple. All that is required isthe name of the command or 
the text of a macro and a key sequence to which it should be bound. The name may be specified in one of two ways: as a 
symbolic key name, possibly with M eta- or Control- prefixes, or as a key sequence. W hen using theform keyname: fund i on- 
name or mac r o, key name is the name of a key spelled out in English. For example, 

Control-u: uni versal-argument 
Meta-Rubout: backward-kill-word 
Control-o: ">&output" 

In the precedi ng example, c-u isbound to thefunction universal-argument, m-del isbound to thefunction backward-kiii- 
word,and c-o isbound to run the macro expressed on therighthand side (that is, to insert the text >&output into the line). 

In the second form, "keys eg": fund i on - name or macro, keyseq differs from keyname in that strings denoting an entire key 
sequence may be specified by placing the sequence within doublequotes. SomeGN U emacs-style key escapes can be used, as 
in thefollowing example: 

"\C-u": uni versal - argument 
"\C-x\C-r": re-read-init-file 
"\e[ 11 '": "Function Key 1 " 

In thisexample, C-u isagain bound to thefunction universal-argument. C-x C-r isbound to thefunction re-read-init-file, 
and esc[ii” isbound to insert the text Function Key i. T hefull set of escape sequences is 


\c- 

Control prefix 

\M - 

M eta prefix 

\e 

An escape character 

\\ 

Backslash 

\" 

Literal" 

V 

Literal ‘ 
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When entering the text of a macro, single or double quotes should be used to indicate a macro definition. U nquoted text is 
assumed to be a function name Backslash will quote any character in the macro text, including" and 

bash allows the current readiine key bindings to be displayed or modified with the bind built-in command. The editing 
mode may be switched during interactive use by using the -o option to the set built-in command. (See "Shell Built-in 
Commands.”) 

Readline has variables that can be used to further customize its behavior. A variable may beset in the input rc file with a 
statement of the form: 
set variable-name value 


Except where noted, readiine variables can take the values on or off. The variables and their default values are as follows: 


horizontal-scroll-mode(Off) 

editing-mode(emacs) 
mark-modified-lines (Off) 
bell-style (audible) 

comment-begin ("#") 
meta-flag (Off) 

convert-meta (On) 

output-meta (off) 
completion-query-items (100) 


keymap(emacs) 


show-all-if-ambiguous (Off) 


expand-tilde (Off) 


When set to on, makes readline use a single line for display, scrolling the input 
horizontally on a single screen line when it becomes longer than the screen width 
rather than wrapping to a new line. 

Controls whether readline begins with a set of key bindings similar to emacs or vi. 
editing-mode Can beSCttO either emacs Or vi. 

If set to on, history linesthat have been modified are displayed with a preceding 
asterisk (*). 

Controls what happens when readiine wants to ring the terminal bell. If set to none, 
readiine never rings the bell. If set to visible, readiine uses a visible bell if one is 
available. If set to audible, readiine attempts to ring the terminal's bell. 

T he string that isinserted in vi mode when thevi-comment command isexecuted. 

If set to on, readiine will enable eight-bit input (that is, it will not strip the high bit 
from the characters it reads), regardless of what the terminal claimsitcan support. 

If set to on, readiine will convert characters with the eighth bit set to an ASCII key 
sequence by stripping the eighth bit and prepending an escape character (in effect, 
usi ng escape as the meta prefix). 

If set to on, readiine will display characters with the eighth bit set directly rather 
than as a meta-prefixed escape sequence. 

This determines when the user is queried about viewing the number of possible 
completions generated by the possible-completions command. It may be set to any 
integer value greater than or equal to zero. If the number of possible completions is 
greater than or equal to the value of this variable, the user is asked whether or not he 
wishes to view them; otherwise they are simply listed on the terminal. 

Set the current readiine keymap. The set of legal keymap names is emacs, emacs- 
standard, emacs-meta, emacs-ctlx, vi, vi-move, vi-command, and vi-insert. vi is 
equivalent to vi-command; emacs is equivalent to emacs-standard. T he default value is 
emacs; the value of editing-mode also affects the default keymap. 

T his altersthe default behavior of the completion functions If set to on, words 
which have more than one possible completion cause the matches to be listed 
immediately instead of ringing the bell. 

If set to on, tilde expansion is performed when readiine attempts word completion. 


Readiine implements a facility similar in spirit to the conditional compilation features of the C preprocessor that allows key 
bindings and variable settings to be performed as the result of tests. There are three parser directives used. 

$if The$if construct allows bindings to be made based on the editing mode the 

terminal being used, or the application using readiine. The text of the test extends 
totheend oftheline; no characters are required to isolate it. 
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The mode= form of the$if directive is used to test whether 
readiine is in emacs or vi mode. This may be used in conjunction 
with theset keymap command, for instance, to set bindingsin the 
emacs-standard and emacs-ctlx kcymapsonly if readline iSStarting 
out in emacs mode. 

term Theterm=forrn may be used to include terminal-specific key 

bindings, perhaps to bind the key sequences output by the 
terminal's function keys. Theword on theright side of the = is 
tested against the full name of the terminal and the portion of the 
terminal name before the first-. This allowssun to match both 
sun and sun-cmd, for instance. 

application T he application construct is used to include application-specific 
settings. Each program using the readiine library sets the 
application name, and an initialization file can test for a particular 
value. Thiscould be used to bind key sequences to functions 
useful for a specific program. For instance the following 
command adds a key sequence that quotes the current or previous 
word in bash: 

$if Bash 

# Quote the current or previous word 
"\C-xq": "\eb\"\ef\"" 

$endif 

$endif This command, as shown in the preceding example, terminates an $if command. 

Seise Commands in this branch ofthesit directive are executed if the test fails 

readiine commands may be given numeric arguments, which normally act as a repeat count. Sometimes, however, it is the 
sign of the argument that is significant. Passing a negative argument to a command that acts in the forward direction (such as 
kiii-iine) causes that command to act in a backward direction. Commands whose behavior with arguments deviates from 
this are noted. 

When a command is described as killing text, the text deleted is saved for possible future retrieval (yanking). The killed text 
issaved in a kill-ring. Consecutive kills cause the text to be accumulated into oneunit, which can be yanked all at once. 
Commands that do not kill text separate the chunks of text on the kill-ring. 

The following is a list of the names of the commands and the default key sequences to which they are bound. 


Commands for M oving 

beginning-of-line(C-a) 
end-of-line (c-e) 
forward-char(C-f) 
backward-char(C-b) 
forward-word (M-f) 

backward-word (M-b) 

clear-screen (C-l) 

redraw-current-line 


M oveto the start of the current line. 

M oveto the end of the line. 

M oveforward a character. 

M ove back a character. 

M ove forward to the end of the next word. Words are composed of alphanu¬ 
meric characters (letters and digits). 

M ove back to the start of this, or the previous, word. Words are composed of 
alphanumeric characters (letters and digits). 

Clear the screen leavi ng the current li ne at the top of the screen. With an 
argument, refresh the current li ne without clearing the screen. 

Refresh the current line. By default, this is unbound. 
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C ommands for M anipulating the H i story 


accept-line (Newline, Return) 


previous-history(c-p) 
next-history(C-n) 
beginning-of-history (M-<) 
end-of-history(M->) 
reverse-search-history(C-r) 

forward-search-history(C-s) 

non-incremental-reverse- 
search-history (M-p) 
non-incremental-forward- 
search-history (M-n) 
history-search-forward 


history-search-backward 


yank-nth-arg (M-C-y) 


yank-last-arg (M-., M-_) 
shell-expand-line(M-C-e) 


history-expand-line (M-') 
insert-last-argument (M-., M-_) 
operate-and-get-next (C-o) 


Accept the line regardless of where the cursor is. Ifthisline is non-empty, add it 
to the history list according to the state of the hist-control variable. If the line is 
a modified history line, then restore the history lineto its original state. 

Fetch the previous command from the history list, moving back in the list. 

Fetch the next command from the history list, moving forward in the list. 

M oveto the first line in the history. 

M oveto the end of the input history, that is the line currently being entered. 
Search backward starting at the current line and moving "up" through the 
history as necessary. T his is an incremental search. 

Search forward starting at the current line and moving "down" through the 
history as necessary. T his is an incremental search. 

Search backward through the history, starting at the current line using anon- 
incremental search for astring supplied by the user. 

Search forward through the hi story using a nonincremental search for astring 
supplied by the user. 

Search forward through the history for the string of characters between the start 
of thecurrent line and thecurrent point. Thisisa nonincremental search. By 
default, this command is unbound. 

Search backward through the history for the stri ng of characters between the start 
of thecurrent line and thecurrent point. Thisisa nonincremental search. By 
default, this command is unbound. 

Insert the first argument to the previous command (usually the second word on 
the previous line) at point (thecurrent cursor position). W ith an argument n, 
insert the nth word from the previous command (the words in the previous 
command begin with word 0). A negative argument inserts thenth word from 
the end of the previous command. 

Insert the last argument to the previous command (the last word on the previous 
line). W ith an argument, behave exactly like ®codefyank-nth-argg. 

Expand the li nethe way the shell does when it reads it. This performs alias and 
history expansion aswell as all of the shel I word expansions. See"FI istory 
Expansion," later in this manual page, for a description of history expansion. 
Perform history expansion on thecurrent line See “FI istory Expansion." 

A Synonym for yank-last-arg. 

Accept the current line for execution and fetch the next line relative to the 
current linefrom the history for editing. Any argument isignored. 


C ommands for C hanging T ext 
delete-char (c-d) 


backward-delete-char(Rubout) 


quoted-insert (C-q, C-v) 


tab-insert (C-v Tab) 

self-insert (a, b, A, 1 ,!,...) 


D elete the character under the cursor. If point is at the beginning of the line, 
there are no characters in the line, and the last character typed was not c-d, then 
return eof. 

Delete the character behind the cursor. W hen given a numeric argument, save 
the deleted text on the kill-ring. 

Add the next character that you type to the line verbatim. This is how to insert 
characters like c-q, for example. 

Insert a tab character. 

I nsert the character typed. 



transpose-chars(C-t) 

D rag the character before point forward over thecharacter at point. Point moves 
forward as well. If point is at the end of the line then transpose the two 
characters before point. N egative arguments don't work. 

transpose-words(M-t) 

Drag the word behind the cursor past the word in front of the cursor, moving 
the cursor over that word as well. 

upcase-word (M-u) 

Uppercase the current (or following) word. W ith a negative argument, do the 
previousword, but do not move point. 

downcase-word (M-l) 

Lowercase the current (or following) word. W ith a negative argument, do the 
previousword, but do not move point. 

capitalize-word(M-c) 

Capitalize the current (or following) word. W ith a negative argument, do the 
previousword, but do not move point. 

Killing and Yanking 


kill-line (C-k) 

K ill the text from the current cursor position to the end of the line. 

backward-kill-line(C-x C-Rubout) 

Kill backward to the beginning of the line. 

UNIX-line-discard(C-u) 

Kill backward from pointto the beginning of theline. 

kill-whole-line 

Kill all characters on the current line no matter where the cursor is By default, 
this is unbound. 

kill-word (M -d) 

Kill from the cursor to the end of the current word, or if between words, to the 
end of the next word. W ord boundaries are the same as those used by forward- 


word. 

backward-kill-word (M-Rubout) 

Kill theword behind thecursor. W ord boundaries are the same as those used by 


backward-word. 

UNIX-word-rubout (C-w) 

Kill theword behind thecursor, using whitespace as a word boundary. Theword 
boundaries are different from backward-kiii-word. 

delete-horizontal-space 

Delete all spaces and tabs around point. By default, thisisunbound. 

yank(C-y) 

Yank the top of the kill ring into the buffer at the cursor. 

yank-pop (M-y) 

Rotate the kill-ring, and yank the new top. Only works following yank or yank- 
pop. 

N u meric Arguments 


digit-argument (M- 0 , M- 1 , —) 

Add this digit to the argument already accumulating, or start a new argument. 
m- starts a negative argument. 

universal-argument 

Each time this is executed, the argument count is multiplied by four. The 
argument count is initially one, so executing thisfunction the first time makes 
the argument count four. By default, thisisnot bound to a key. 

Completing 


complete (tab) 

Attempt to perform completion on the text before point. Bash attempts 
completion treati ng the text as a variable (if the text begins with $), username (if 
thetext beginswith •), hostname (if the text beginswith @), or command 
(including aliases and functions) in turn. If none of these produces a match, 
filename completion is attempted. 

possible-completions (m-?) 

List the possible completions of the text before point. 

insert-completions 

Insert all completionsof thetext before point that would have been generated by 
possible-completions. By default, this is not bound to a key. 

complete-filename(M-/) 

Attempt filename completion on thetext before point. 


continues 
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Completing 

possible-filename-completions(C-x /) 
complete-username(M-‘) 
possible-username-completions(C-x ') 
complete-variable( m-$) 
possible-variable-completions(C-x $) 

complete-hostname(M-@) 
possible-hostname-completions(C-x @) 
complete-command (M-!) 


possible-command-completions (C-x l) 
dynamic-complete-bistory (M-TAB) 
complete-into-braces (M-{) 


List the possible completions of the text before point, treating it as a filename. 
Attempt completion on thetext before point, treating itasa username. 

List the possible completions of the text before point, treating it as a username. 
Attempt completion on thetext before point, treating it as a shell variable 
List the possible completions of thetext before point, treating it as a shell 
variable. 

Attempt completion on thetext before point, treating it as a hostname. 

List the possible completions of thetext before point, treating it as a hostname. 
Attempt completion on thetext before point, treating it as a command name. 
Command completion attempts to match thetext against aliases, reserved words, 
shell functions, builtins, and finally executable filenames, in that order. 

List the possible completions of thetext before point, treating it as a command 
name. 

Attempt completion on thetext before point, comparing thetext against lines 
from the history listfor possiblecompletion matches. 

Perform filename completion and return the list of possible completions enclosed 
within braces so the list is available to the shell. (See "Brace Expansion," earlier in 
this manual page.) 


K e/board M acros 

start-kbd-macro(C-x () 
end-kbd-macro (C-x )) 


call-last-kbd-macro (C-x e) 


Begin saving the characters typed into the current keyboard macro. 

Stop saving the characters typed into the current keyboard macro and save the 
definition. 

Re-execute the last keyboard macro defined, by making the characters in the 
macro appear as if typed at the keyboard. 


M i 9 cellaneous 

re-read-init-file(C-x C-r) 
abort(C-g) 

do-uppercase-version (M-a, M-b, ...) 
prefix-meta (ESC) 
undo (c-_, C-x C-u) 
revert-line (M-r) 

tilde-expand (M-') 
dump-functions 


display-shell-version (c-x C-v) 
emacs-editing-mode(C-e) 


Read in the contents of your i nit file and incorporate any bindings or variable 
assignments found there. 

Abort the current editing command and ring the terminal's bell (subject to the 
setting of bell-style). 

Run thecommand that is bound to the corresponding uppercase character. 
Metafy the next character typed. ESC-f isequivalentto Meta-f. 

Incremental undo, separately remembered for each line. 

Undo all changes made to this line. This is I ike typing the undo command 
enough times to return thelineto its initial state. 

Perform ti Ide expansion on the current word. 

Print all of the functions and their key bindings to thereadiine output stream. If 
a numeric argument is supplied, the output is formatted in such away that it can 
be made part of an inputrcfile. 

D isplay version information about the current instance of bash. 

When in vi editing mode this causes a switch to emacs editing mode. 


HISTORY 

When interactive, the shell provides access to thecommand history, the list of commands previously typed. Thetext of the 
last histsize commands (default 500) is saved in a history list. The shell stores each command in the history list prior to 
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parameter and variable expansion (see "Expansion," earlier in this manual page) but after history expansion is performed, 
subject to the values of the shell variables command_oriented_history and histcontrol. On startup, the history is initialized 
from the file named by the variable histfile (default '/.bashjiistory). HI ST FILE is truncated, if necessary, to contain no 
more than histfilesize lines. The built-in command fc (see Shell Built-in Commands, later in this manual page) may be 
used to list or edit and re-execute a portion of the history list. The history builtin can be used to display the history list and 
manipulate the history file. W hen using the command-line editing, search commands are available in each editing mode that 
provide access to the history list. W hen an interactive shell exits the last histsize lines are copied from the history list to 
histfile. If histfile is unset, or if the history file is unwritable, the history is not saved. 


HISTORY EXPANSION 

The shell supports a history expansion feature that is similar to the history expansion in csh. This section describes what 
syntax features are available. This feature is enabled by default for interactive shells, and can be disabled using the h option to 
the set built-in command. (See"Shell Built-in Commands,” later in this manual page.) N oninteractiveshells do not perform 
history expansion. 

H i story expansion isperformed immediately after a complete line is read, before the shell breaks it into words. It takes place 
in two parts. The first isto determinewhich line from the previous history to use during substitution. Thesecond isto select 
portions of that line for inclusion into the current one. The line selected from the previous history is the event, and the 
portions of that line that are acted upon are words. The line is broken into words in the same fashion as when reading input, 
so that several meta character-separated words surrounded by quotes are considered as oneword. 0 nly the backslash (\) and 
single quotes can quote the history escape character, which is! by default. 

Theshell allows control of thevariouscharactersused by the history expansion mechanism. (See the description of histchars 
under "Shell Variables," earlier in thismanual page.) 


EVENT DESIGNATORS 

An event designator is a reference to a command line entry in the history list. 


!n 

!-n 

1 st r i ng 
!?stri ng [?] 

"st r i ngl A st r i ng 2 * 


!# 


Start a history substitution, except when followed by a blank, newline, =, or (. 

Refer to the previous command. This is a synonym for 1-1. 

Refer to command linen. 

Refer to the current command line minusn. 

Refer to the most recent command starting with stri ng. 

Refer to the most recent command containing stri ng. 

Quick substitution. Repeat the last command, replacing st r i ng 1 with stri ng2. Equivalent to 11 :s/ 
stri ngi /stri ng 2 /. (See "M odifiers," later in thismanual page.) 

The entire command linetyped so far. 


WORD DESIGNATORS 

A colon (:) separates the event specification from the word designator. It can be omitted if the word designator begins with a 
\ $, *, or%. Words are numbered from the beginning of the line, with the first word being denoted by a a (zero). 

a (zero) The zeroth word. For the shell, this isthe command word, 

n The nth word. 

Thefirst argument. That is, word 1 . 

$ The last argument. 

% The word matched by the most recent ?string? search, 

x-y A range of words; -y abbreviates a-y. 

* All of the words but the zeroth. This is a synonym for i-$. It is not an error to use* if there is just 

oneword in the event; the empty string is returned in that case, 
x* Abbreviates x-$. 

x- Abbreviates x-$ like x*, but omitsthe last word. 
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MODIFIERS 


After theoptional word designator, you can add a sequenceof oneor moreof the following modifiers, each preceded by a : 


h 

r 

e 

t 

P 

q 

X 

s/ol d /new/ 


& 


g 


Remove a trailing pathname component, leaving only the head. 

Remove a traiIing suffix of the form .xxx , leaving the basename. 

Remove all but thetrailing suffix. 

Remove all leading pathname components, leaving the tail. 

Print the new command but do not execute it. 

Quote the substituted words, escaping further substitutions 

Quote the substituted words as with q, but break into words at blanks and newlines. 

Substitute new for the first occurrence of o i d in the event line. Any delimiter can beused in place of 
/.The final delimiter is optional if it is the last character of the event line. The deli miter may be 
quoted in old and new with a single backslash. If & appears in new, it is replaced by o i d. A single 
backslash will quote the&. 

Repeat the previous substitution. 

Cause changes to be applied over the entire event line. This is used in conjunction with :s (for 
example, :gs/oi d /new/) or If used with :s, any delimiter can beused in placeof /, and the final 
delimiter is optional if it is the last character of thea/ent line. 


ARITHMETIC EVALUATION 

Theshell allows arithmetic expressionsto be evaluated, under certain circumstances. (Seetheiet built-in command and 
"Arithmetic Expansion.'') Evaluation is done in long integers with no check for overflow, though division by 0 is trapped and 
flagged as an error. The following list of operators is grouped into levels of equal-precedence operators. The levels are listed 
in order of decreasing precedence. 

-+ Unary minus and plus 

i ' Logical and bitwise negation 

* / % M ultiplication, division, remainder 

+ - Addition, subtraction 

«» Left and right bitwise shifts 

<= >= <> Comparison 

== i= Equality and inequality 

& Bitwise AND 

* BitwiseexclusiveoR 

; Bitwise or 

&& Logical and 

II Logical or 

= *= /= %= += _= «= »=&=■=!= Assignment 

Shell variables are allowed asoperands parameter expansion isperformed before the expression isevaluated. Thevalueof a 
parameter is coerced to a long integer within an expression. A shell variable need not have its integer attribute turned on to 
beused in an expression. 

C onstants with a leading 0 are interpreted as octal numbers.A leading ox or ox denotes hexadecimal. Otherwise, numbers 
taketheform [ba s e #]n , where base is a decimal number between 2 and 36 representing the arithmetic base, and n isa 
number in that base. If base is omitted, then baselO isused. 

0 perators are evaluated in order of precedence. Subexpressions in parentheses are evaluated first and may override the 
precedence rules. 



SHELL BUILT-IN COMMANDS 

: [arguments ] 

. f i I e n a me [ a r g u me n t s ] 
source f i I ena me [arguments] 


alias [name [ =v a I ue ] ... ] 


bg [j obspec ] 


bind [-m key map ] [-lvd] [-q name] 
bind [-m keymap] -f filename 
bind [-m keymap] 
k e y s e q: f u n c t i o n - n a me 


break [n ] 


builtin s hel I - bui 11 i n [arguments] 


cd [di r ] 


bash 


N o effect; the command does nothing beyond expanding arguments and performing 
any specified redirections. A zero exit code is returned. 

Read and execute commands from fi i ena me in the current shell environment and 
return the exit status of the last command executed from filename. Iffiiename does 
not contain a slash, pathnames in path are used to find the directory containing 
filename. The file searched for in path need not be executable. The current directory 
is searched if no file is found in path. If any arguments are supplied, they become the 
positional parameters when tile isexecuted. Otherwise, the positional parameters 
are unchanged. The return status is the status of the last command exited within the 
script (0 if no commands are executed), and False if filename is not found, 
alias with no arguments prints the list of aliases in theform name=vai ue on standard 
output. W hen arguments are supplied, an alias is defined for each name whose value 
is given. A trailing space in value causes the next word to be checked for alias 
substitution when the alias is expanded. For each name in theargument list for 
which no value is supplied, the name and value of the alias is printed, alias returns 
True unless a name is given for which no alias has been defined. 

Place] obspec in the background, as if it had been started with &. If j obspec is not 
present, the shell's notion of the current job isused. bg jobspec returns 0 unless run 
when job control is disabled or, when run with job control enabled, if jobspec was 
notfound or started without job control. 

D i splay current readiine key and function bindings, or bind a key sequence to a 
readiine function or macro. T he bi nding syntax accepted is identical to that of 
.inputrc, but each binding must be passed as a separate argument; for example, 
"\c-x\c-r": re-read-init-fiie. Options if supplied, have thefollowing meanings: 

-m keymap Usekeymap as the keymap to be affected by the subsequent 

bindings. Acceptable key map names are emacs, emacs-standard, 
emacs-meta, emacs-ctlx, vi, vi-move, vi-command, and vi-insert. 
vi is equivalent to Vi-command; emacs is equivalent to emacs- 
standard. 

-1 List the names of all readiine functions. 

-v List current function names and bindings. 

-d Dump function names and bindings in such a way that they 

can be reread. 

-f f i 1 ename Read key bindingsfrom filename 

-q function Q uery about which keys invokethe named function. 

The return value is 0 unless an unrecognized option is given or an error occurred. 
Exit from within a tor, while, or until loop. If n is specified, break n levels, n must 
be 1. If n is greater than the number of enclosing loops, all enclosing loops are 
exited. The return value is 0 unless the shell is not executing a loop when break is 
executed. 

Execute the specified shell builtin, passing it arguments, and return its exit status. 
This is useful when you wish to define a function whose name is the same as a shell 
builtin, but need the functionality of the builtin within the function itself. T heed 
builtin iscommonly redefined this way. The return statusisFaise if s he 1 -bui 1 ti n is 
not a shell builtin command. 

Change the current directory to d i r . The variable home is the default di r . The 
variablecDPATH defines the search path for the di rectory containing dir. Alternative 
directory names are separated by a colon (:). A null directory name in cdpath isthe 
same as the current directory, that is (.). If di r beginswith a slash (/), then cdpath is 
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command [-pVv] command [arg ...] 


continue [n] 


declare [-frxi][name[=val ue ]] 
typeset [-frxi][name[=val ue]] 


dirs [-1][+/-n ] 


echo [-neE][arg ... ] 


not used. An argument of - is equivalent to soldpwd. The return value is True if the 
directory was successfully changed; False otherwise. 

Run command with args suppressing the normal shell function lookup. Only built- 
in commands or commands found in thePATH are executed. If the -p option is given, 
the search for command is performed using a default value for path that is guaranteed 
to find all of the standard utilities. If either the-v or -v option is supplied, a 
description of command is printed. T he -v option causes a single word indicating the 
command or pathname used to invoke command to be printed; the-v option 
produces a more verbose description. An argument of - disables option checking for 
the rest of the arguments. If the-v or -v option is supplied, the exit status is® if 
command was found, and i if not. If neither option is supplied and an error occurred 
orcommand cannot be found, the exit status is 127. Otherwise, the exit status of the 
command builtin is the exit Status Of c omma nd. 

Resume the next iteration of the enclosing tor, while, or until loop. If n is specified, 
resumeat the nth enclosing loop, n must be 1. If n is greater than the number of 
enclosing loops, the last enclosing loop (the top-level loop) is resumed. The return 
value iso unless theshell is not executing a loop when continue is executed. 

Declare variables and/or give them attributes. If no names are given, then display the 
values of variables instead. The options can be used to restrict output to variables 
with the specified attribute. 

-f Usefunction namesonly. 

-r M ake names read-only. These names cannot then be assigned 

values by subsequent assignment statements 
-x M ark names for export to subsequent commands via the 

environment. 

-i The variable istreated as an integer; arithmetic evaluation (see 

"Arithmetic Evaluation”) is performed when the variable is 
assigned a value. 

Using + instead of - turns off the attribute instead. W hen used in a function, makes 
names local, as with the local command. T he return value is 0 unless an illegal 
option is encountered, an attempt ismadeto define a function using ”-f toolbar 1 , 
one of the names is not a legal shell variable name, an attempt ismadeto turn off 
read-only status for a read-only variable, or an attempt ismadeto display a 
nonexistent function with -t. 

D isplay the list of currently remembered directories. D irectories are added to the list 
with the pushd command; the popd command moves back up through the list. 

+n D i splays the nth entry counting from the left of the list shown 

by dirs when invoked without options starting with zero. 

-n D i splays the nth entry counting from the right of the list 

shown by dirs when invoked without options, starting with 
zero. 

-1 Produces a longer listing; the default listing format uses a tilde 

to denote the home directory. 

The return value iso unless an illegal option is supplied orn indexes beyond the end 
of the directory stack. 

Output the args, separated by spaces. The return status is always 0. If -n is specified, 
thetrailing newline is suppressed. Ifthe-e option isgiven, interpretation of the 
following backslash-escaped characters is enabled. The -e option disables the 
interpretation of these escape characters, even on systems where they are interpreted 
by default. 
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\a 

Alert (bell) 

\b 

Backspace 

\c 

Suppress trailing newline 

\f 

Form feed 

\n 

N ewline 

\r 

Carriage return 

\t 

Horizontal tab 

\v 

Vertical tab 

\\ 

Backslash 

\nnn 

The character whose ASCII code isn nn (octal) 


enable [-n] [-aii] [name ...] Enableand disable builtin shell commands. T hi sal lows the execution of a disk 

command that has the same name as a shell builtin without specifying a full 
pathname. If -n is used, each name is disabled; otherwise, names are enabled. For 
example, to use the test binary found via the path instead of the shell builtin version, 
type enable -n test. If no arguments are given, a list of all enabled shell builtinsis 
printed. If only -n is supplied, a list of all disabled builti ns is printed. If only -an is 
supplied, the list printed includes all builti ns, with an indication of whether or not 
each is enabled, enable accepts -a as a synonym for -an. The return value iso unless 
a name is not a shell builtin. 

evai [a r g ...] T he args are read and concatenated together into a single command. T hiscommand 

is then read and executed by the shell, and its exit status is returned as the value of 
the evai command. If there are no args, or only null arguments, evai returns True, 
exec [[-] command [arguments]] If c o mma n d is specified, it replaces the shell. N o new process is created. T he arguments 

become the arguments to command. If the first argument is-, the shell places a dash in 
thezeroth arg passed to command. This is what login does. If thefile cannot be 
executed for some reason, a noninteractive shell exits, unless the shell variable 
no_exit_on_faiied_exec exists, in which caseit returns fai lure. An interactive shell 
returns failure if thefilecannot be executed. If command isnot specified, any 
redirections take effect in the current shell, and the return status iso. 
exit [n] C ause the shell to exit with a status of n . If n is omitted, the exit status isthat of the 

last command executed. A trap on exit isexecuted before the shell terminates, 
export [ - nt ] [name [ =wo r d ] ] ... T he suppl ied names are marked for automatic export to the environment of 

export -p subsequently executed commands. If the -f option isgiven, the names refer to 

functions. If no names are given, or if the -p option is supplied, a list of all names 
that are exported in this shell is printed. The -n option causes the export property to 
be removed from the named variables. An argument of - disables option checking 
for the rest of the arguments, export returns an exit status of 0 unless an illegal 
option is encountered, one of the names is not a legal shell variable name, or -f is 
supplied with a namethat isnot a function. 

to [-e ename n-nir] [f i r s t ] [i a s t ] Fix command. I n the first form, a range of commands from f i rst to 1 as t is selected 

to-s [pat =r ep ] [c md ] from the history list, first and last may be specified as a string (to locate the last 

command beginning with that string) or as a number (an index into the history list, 
where a negative number is used as an offset from the current command number). If 
last is not specified, it is set to the current command for listing (so that fc -1 
-10 prints the last 10 commands) and to first otherwise. If first isnot specified, it 
is set to the previous command for editing and -16 for listing. 

The-n flag suppresses the command numbers when listing. The -r flag reverses the 
order of the commands. If the-1 flag isgiven, the commands are listed on standard 
output. Otherwise the editor given byename isinvoked on a file containing those 
commands. If ename is not given, the value of the fcedit variable is used, and the 
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value of editor if fcedit isnot set. If neither variable is set, vi is used. W hen editing 
is complete, the edited commands are echoed and executed. 

In the second form, command is reexecuted after each instance of pat isreplaced by 
rep. A useful alias to use with this is r=tc -s, so that typing r cc runs the last 
command beginning with cc and typing r reexecutes the last command. 

If the first form is used, the return value iso unless an illegal option is encountered 
or f i r st or i as t specify history lines out of range. If the-e option is supplied, the 
return value is the value of the last command executed or failure if an error occurs 
with the temporary file of commands. If thesecond form isused, thereturn status is 
that of the command reexecuted, unless cmd does not specify a valid history line, in 
which casetc returnsfailure. 

fg [jobspec] Place] obspec in theforeground, and make it the current job. Ifjobspec isnot 

present, the shell's notion of the current job isused. Thereturn value is that of the 
command placed into theforeground, or failure if run when job control is disabled 
or, when run with job control enabled, ifjobspec does not specify a valid job or 
jobspec specifies a job that was started without job control. 

getopts optstring name [args] getopts is used by shell procedures to parse positional parameters, opt st r i ng contains 

the option letters to be recognized; if a letter is followed by a colon, the option is 
expected to have an argument, which should be separated from it by whitespace. 

Each time it is invoked, getopts pi aces the next option in the shell variable name, 
initializing name if it does not exist, and the index of the next argument to be 
processed into the vari able optind. optind isinitialized to i each time the shell or a 
shell script is invoked. When an option requires an argument, getopts places that 
argument into the vari able optarg. The shell does not reset optind automatically; it 
must be manually reset between multiple cal Is to getopts within the same shell 
invocation if a new set of parameters is to be used. 

getopts can report errors in two ways. If the first character of optstri ng is a colon, 
silent error reporting is used. In normal operation, diagnostic messages are printed 
when illegal options or missing option arguments are encountered. If thevariable 
opterr is set to 0, no error message will be displayed, even if the first character of 
optstri ng isnotacolon. 

If an illegal option is seen, getopts places a question mark (?) into name and, if not 
silent, prints an error message and unsets optarg. If getopts is si lent, theoption 
character found is placed in op-targ and no diagnostic message is printed. 

If a required argument is not found, and getopts is not si lent, a question mark (?) is 
placed in name, optarg i s u n set, and a diagnostic message is printed. If getopts is 
silent, then a colon (:) is placed in name and optarg is set to theoption character 
found. 

getopts normally parses the positional parameters, but if more arguments are given 
in args, getopts parses those instead, getopts returnsTrue if an option, specified or 
unspecified, is found. It returns False if the end of options is encountered or an error 
occurs. 

hash [ - r] [name ] Foreach name, thefull pathnameof the command is determined and remembered. 

The -r option causes the shell to forget all remembered locations. If no arguments 
are given, information about remembered commands is printed. An argument of - 
disables option checking for the rest of the arguments. Thereturn status isTrue 
unless a name is not found or an illegal option issupplied. 

help [pattern ] D isplay helpful information about built-in commands. If pattern is specified, help 

gives detailed help on all commands matching pattern; otherwise, a list of the 
builtins is printed. Thereturn status is 0 unless no command matches pattern. 



history [n] 

history -rwan [filename] 
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jobs [ -lnp ][j obspec ... ] 
jobs -x command [ args ... ] 


kill [-s sigspec \ -si gs pec ] 
[pi d | j obspec ] ... 
kill -1 [si gnum] 


let ar g [ar g ... ] 
local [name[ =v a I u e] ... ] 


logout 
popd [+/-n ] 


With no options, display the command history list with line numbers. Lines listed 
with a* have been modified. An argument of n lists only the/astn lines. If a 
nonoption argument is supplied, it is used as the name of the history file; if not, the 
value of histfile isused. Options, if supplied, have the followi ng meanings: 

-a Append the "new" history lines (history linesentered sincethe 

beginning of the current bash session) to the history file. 

-n Read the history lines not already read from the history file 

into the current history list. T hese are lines appended to the 
history file si nee the beginning of the current bash session. 

-r Read the contents of the history file and use them asthe 

current history. 

w- W ritethe current history to the history file, overwritingthe 

history file's contents. 

The return value iso unless an illegal option is encountered or an error occurs while 
reading or writing the history file. 

The first form I ists the active jobs. The-1 option lists process ID sin addition to 
the normal information; the -p option lists only the process ID of the job's process 
group leader. The-n option displays onlyjobs that have changed status since last 
notified. I f j o bs pec is given, output is restricted to information aboutthatjob.The 
return status iso unless an illegal option is encountered or an illegal j obs pec is 
supplied. 

If the -x option issupplied, jobs replaces any j obs pec found in command or a r g s with 
the corresponding process group ID, and executes command, passing itargs, returning 
its exit status. 

Send the signal named by sigspec to the processes named by pi d or j obs pec. si gs pec 
iseither a signal namesuch as sigkill or a signal number. Ifsigspec is a signal 
name, the name is not case sensitive and may be given with or without the sig 
prefix. If sigspec is not present, then sigterm is assumed. An argument of -l lists the 
signal names. If any arguments are supplied when -l is given, the names of the 
specified signals are listed, andthereturn status is 0. An argument of - disables 
option checking for the rest of the arguments kin returns True if at least one signal 
was successfully sent, or False if an error occurs or an illegal option is encountered. 
Each a r g is an arithmetic expression to be evaluated. (See "Arithmetic Evaluation.”) 
If the last a r g evaluates to 0, let returnsi; 0 is returned otherwise. 

For each argument, createa local variablenamed name, and assign it va 1 ue. When 
local isused within afunction, it causes thevariablename to have a visible scope 
restricted to that function and its children. With no operands, local writesa list of 
local variables to the standard output. It is an error to use local when not within a 
function. The return status is 0 unless local isused outside a function, or an illegal 
name is supplied. 

Exit a login shell. 

Removes entries from the directory stack. W ith no arguments removes the top 
directory from the stack, and performs a cd to the new top directory. 

+n Removesthenth entry counting from the left of the list shown 

bydirs, starting with zero. For example, popd +0 removes the 
first directory, popd +1 the second. 

-n Removesthenth entry counting from the right of the list 

shown bydirs, starting with zero. For example, popd -0 
removes the last directory, popd -1 the next to last. 



40 


Parti: User Commands 


pushd [dir] pushd +/-n 


pwd 


read [-r] [name ... ] 


readonly [-f ] [name ... ] 
readonly -p 


return [n ] 


set [—abefhkmnptuvxldCHP] 
[-o option][arg ...] 


If the popd command is successful, a dirs is performed as well, and the return status 
is 0. popd returnsFaise if an illegal option isencountered, the directory stack is 
empty, a nonexistent directory stack entry is specified, or the directory change fails. 
Adds a directory to the top of the di rectory stack, or rotates the stack, maki ng the 
new top of the stack the current working directory. With no arguments, exchanges 
thetop two directories and returns©, unlessthedirectory stack isempty. 

+n Rotates the stack so that the nth directory (counting from the 

left of the list shown by dirs) is at thetop. 

-n Rotates the stack so that the nth directory (counting from the 

right) is at the top. 

dir Adds d i r to the directory stack at the top, making it the new 

current working directory. 

If the pushd command is successful, a dirs is performed as well. If thefirst form is 
used, pushd returns© unless thecd to di r fails. W ith the second form, pushd returns© 
unless the directory stack isempty, a nonexistent directory stack element is specified, 
or the directory change to thespecified new current directory fails. 

Print the absolute pathname of the current working directory. The path printed 
contains no symbolic links if the -p option to the set builtin command is set. (See 
also the description of noiinks under "Shell Variables,'' earlier in this manual page.) 
The return status is© unless an error occurs whilereading thepathnameof the 
current directory. 

One line is read from the standard input, and the first word is assigned to thefirst 
name, the second word to the second name, and so on, with leftover words assigned 
to the last name. Only the characters in ifs are recognized as word delimiters. If no 
names are supplied, the line read is assigned to the variable reply. The return codeis 
zero, unless end-of-file is encountered. If the - n option isgiven, a backslash-newline 
pair is not ignored, and the backslash is considered to be part oftheline. 

T he given names are marked readonly and the values of these names may not be 
changed by subsequent assignment. Ifthe-f option is supplied, the functions 
corresponding to the names are so marked. If no arguments are given, or if the 
-p option is supplied, a list of all readonly names is printed. An argument of - 
disables option checking for the rest of the arguments. The return status is© unless 
an illegal option isencountered, oneof the names is not a legal shell variablename, 
or-t is supplied with a name that is not a function. 

Causes a function to exitwith thereturn value specified by n. If n isomitted, the 
return status is that of the last command executed in thefunction body. Ifused 
outside a function, but during execution of a script by the . (source) command, it 
causes the shell to stop executing that script and return either n or the exit status of 
the last command executed within the scri pt as the exit status of the script. Ifused 
outside a function and not during execution of a script by (. , thereturn status is 
False. 


-a Automatically mark variables that are modified or created for 

export to the environment of subsequent commands. 

-b Cause the status of terminated background jobs to be reported 

immediately, rather than before the next primary prompt. 
(Also see notify under "Shell Variables.'') 

-e Exit immediately if a simple command (see "Shell G rammar," 

earlier in this manual page) exits with a non-zero status. The 
shell does not exit if the command that fails is part of an until 
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or while loop, part of an it statement, part of a m or \ \ list, or 
if the command's return valueisbeing inverted via i. 

-f Disable pathnameexpansion. 

-h Locate and remember fundi on commands as functions are 

defined. Function commands are normally looked up when 
the function is executed. 

-k All keyword arguments are placed in the environment for a 

command, not just those that precede thecommand name. 

-m Monitor mode. Job control is enabled. T hisflag is on by 

default for interactive shells on systems that support it. (See 
"Job Control," earlier in thismanual page.) Background 
processes run in a separate process group and aline containing 
their exit status is printed upon their completion. 

-n Read commands but do not execute them. This may be used 

to check a shell script for syntax errors. This is ignored for 
interactive shells 

-o option-name Theoption-name can be one of the following: 
aiiexport— Same as -a. 

braceexpand—The shell performs brace expansion. (See"Brace 

Expansion," earlier in thismanual page.) This is on by default. 

emacs—Usean emacs-stylecommand lineediting interface. 

This is enabled by default when the shell is interactive, unless 

the shell is started with the -noiineediting option. 

errexit — Same 3 S -e. 

histexpand — Same as -H. 

ignoreeof— The effect isasif the shell command 

1 ignoreeof=i0 had been executed. (See"Shell Variables.") 

interactive-comments— Allow a word beginning with # to 

cause that word and all remaining characters on that line to be 

ignored in an interactive shell. (See "Comments," earlier in 

thismanual page.) 

monitoi — Same as -m. 

nociobber — Same as -C. 

noexec — Same as -n. 

nogiob — Same as -f . 

nohash — Same as -d. 

notify — Same as -b. 

nounset— Same as -u. 

physical— Same as -p. 

posix— C hange the behavior of bash where the default 
operation differs from the POSIX 1003.2 standard to match 
the standard, 
privileged— Same 3 S -p. 
verbose — Same as -v. 

vi— U se a vi- style command line editing i nterface. 
xtrace — Same as -x. 

If no opti on-name is supplied, the values of the current options 
are printed. 
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-p T urn on privileged mode. In this mode, the$ENv file is not 

processed, and shell functions are not inherited from the 
environment. This is enabled automatically on startup if the 
effective user (group) ID is not equal to the real user (group) 

ID .T urning this option off causes the effective user and group 
ID s to be set to the real user and group ID s. 

-t Exit after reading and executing onecommand. 

-u Treat unset variables as an error when performing parameter 

expansion. If expansion isattempted on an unset variable, the 
shell prints an error message, and, if not interactive, exits with 
a non-zero status. 

-v Printshell input linesasthey are read. 

-x After expanding each simple command, bash displaysthe 

expanded value of PS4, followed by the command and its 
expanded arguments. 

-l Saveand restorethe binding of name in ator name [in word] 

command. (See"Shell Grammar,’’ earlier in thismanual page.) 
-d D isablethe hashing of commandsthat are looked up for 

execution. Normally, commands are remembered in a hash 
table, and once found, do not have to be looked up again. 

-c T he effect is as if the shell command nociobber= had been 

executed. (See"Shell Variables.'') 

-h Enable ! style history substitution. Thisflag is on by default 

when theshell is interactive. 

-p If set, do not follow symbolic links when performing 

commands such ascd that change the current directory. The 
physical directory is used instead. 

If no arguments follow this flag, then the positional parameters 
are unset. Otherwise, the positional parameters are set to the 
args, even if some of them begin with a-. 

Signal theend of options, cause all remainingargs to be 
assigned to the positional parameters. T he -x and -v options 
are turned off. If there are no args, the positional parameters 
remain unchanged. 

T he flags are off by default unless otherwise noted. Using + 
rather than - causes these flags to be turned off. T he flags can 
also be specified as options to an invocation of theshell. The 
current set of flags may be found in $-. After the option 
arguments are processed, theremainingn args are treated as 
values for the positional parameters and are assigned, in order, 
to $1, $2, ... $n. If no options or args are supplied, all shell 
variables are printed. The return status is always True unless an 
illegal option is encountered. 

shift [n] T he positional parameters from n+i ... are renamed to .... Parameters represented 

by the numbers?# down to $#-n+i are unset. If n is e, no parameters are changed. If 
n is not given, it is assumed to be i. n must be a non-negative number less than or 
equal to $#. If n is greater than $#, the positional parameters are not changed. The 
return status is greater than 0 if n isgreaterthan or less than 0; otherwise@. 

Suspend the execution of this shell until it receives a sig-cont signal. The -1 option 
says not to complain if this is a login shell; just suspend anyway. The return status is 


suspend [-f] 



test expr[exp r ] 


times 
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0 unless the shell isa login shell and -f isnot supplied, or if job control is not 
enabled. 

Return a status of 0 (True) or 1 (False) depending on the evaluation of the 
conditional expression expr. Expressions may be unary or binary. U nary expressions 
are often used to examine the status of a file There are string operators and numeric 
comparison operators as well. Each operator and operand must bea separate 
argument. If file is of the form /dev/fd/n, then file descriptor n is checked. 


-b f 

1 e — True if f 

1 e exists and is block special. 

-c f 

1 e — True if f 

1 e exists and ischaracter special. 

-d f 

1 e — True if f 

1 e exists and isa directory. 

-e f 

1 e — True if f 

1 e exists. 

-f f 

1 e — True if f 

1 e exists and isa regular file. 

-g f 

1 e — True if f 

ie exists and isset-group-id. 

-k f 

1 e — True if f 

1 e has its "sticky" bit set. 

-L f 

1 e — True if f 

1 e exists and isa symbolic link. 

-p f 

1 e — True if f 

1 e exists and isa named pipe. 

-r f 

1 e — True if f 

1 e exists and is readable. 

-s f 

1 e — True if f 

1 e exists and has a size greater than zero. 

-S f 

1 e — True if f 

1 e exists and isa socket. 

-t fd— True if f d isopened on a terminal. 

-u f 

1 e — True if f 

1 e exists and its set-user-id bit is set. 

-w f 

1 e — True if f 

1 e exists and iswritable. 

-X f 

1 e — True if f 

1 e exists and is executable. 

-0 f 

1 e — True if f 

1 e exists and is owned by the effective user 1D. 

-G f 

1 e — True if f 

1 e exists and is owned by the effective group ID 


fi 1 ei -nt f i 1 e 2 —True iffi i ei isnewer (accordingto modification date) than 
fiIe2. 

f i I el -ot f 11 e 2—True if f i I el is Older than f i I e2. 

f i 1 ei -ef f i 1 e—True iff i i ei and f i i e 2 have the same device and inode 

numbers. 

-z stri ng—True if the length of stri ng iszero. 

■ n stri ng — True if the length of str i ng is non-zero, 
stri ngi = stri n g 2 — True if the strings are equal, 
stri ngi t= stri n g 2 — True if the stri ngs are not equal. 

! expr — Trueifexpr iSFalse. 

exprl -a e x p r 2 — T rue if both exprl AND e x p r 2 are True. 

exprl -o e x p r 2 — T rue if either exprl OR e x p r 2 iSTrue. 

ar gi op arg 2 op isoneof -eq, -ne, -it, -le, -gt, or -ge. Thesearithmetic binary 

operators return True if argi isequal, not-equal, less-than, less-than-or-equal, 

greater-than, or greater-than-or-equal than arg 2 , respectively. Argi and arg 2 may 

be positive integers, negative integers, or the special expression -1 stri ng, which 

evaluates to the length ofstri ng. 

Print the accumulated user and system times for the shell and forprocesses run from 
the shell. The return status iso. 

Thecommand arg istoberead and executed when the shell receives si gnal(s) 
si gspec. If arg is absent or -, all specified signals are reset to thei r original values (the 



trap [-1][ar g ] [si gs pec ] 
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values they had upon entrance to the shell). If arg isthenull string, this signal is 
ignored by theshell and by the commands it invokes, si gs pec is either a signal name 
defined in <signai.h>, or a signal number. If si gs pec is exit (0), the command arg 
isexecuted on exitfrom theshell. With no arguments, trap prints the list of 
commands associated with each signal number. The-i option causes the shell to 
print a list of signal names and their corresponding numbers. An argument of - 
disables option checking for the rest of the arguments. Signals ignored upon entry to 
theshell cannot be trapped or reset. T rapped signals are reset to their original values 
in achild process when it is created. The return statusisraise if either the trap name 
or number is invalid; otherwise, trap returnsTrue. 

type [-ail] [-type | -path] W ith no options, indicate how each namewould be interpreted if used as a 

name [name ...] command name. If the -type flag is used, type prints a phrase that is one of alias, 

keyword, function, buiitin, or file if name isan alias, shell reserved word, function, 
builtin, or disk file respectively. If the name is not found, then nothing isprinted, 
and an exit status of False is returned. If the -path flag is used, type either returns 
the name of the disk file that would be executed if name were specified asacommand 
name, or nothing if -type would not return file. If a command is hashed, -path 
prints the hashed value, not necessarily the file that appears first in path. If the-aii 
flagisused, type prints all of the places that contain an executable named name. This 
includes aliases and functions, if and only if the -path flag is not also used. The table 
of hashed commands is not consulted when using -ail. type accepts -a, -t, and -p in 
placeof -ail, -type, and -path, respectively. An argument of - disablesoption 
checki ng for the rest of the arguments, type returns True if any of the arguments are 
found, False if none are found. 

uiimit [-sHacdtmstpnuv [limit]] uiimit provides control over the resources available to the shell and to processes 

started by it, on systems that allow such control. The value of limit can be a number 
in the unit specified for the resource, or thevalue unlimited. T he h and s options 
specify that the hard or soft limit is set for the given resource. A hard limit cannot be 
increased once it is set; a soft limit may be increased up to thevalue of the hard 
limit. If neither h nor s is specified, the command applies to the soft limit. If limit is 
omitted, the current value of the soft limit of the resource isprinted, unless the h 
option is given. When more than one resource is specified, the limit name and unit 
isprinted before the value. Other options are interpreted as follows: 

-a All current limits are reported. 

-c Themaximum size of core files created. 

-d Themaximum size of a process's data segment. 

-f Themaximum size of files created by theshell. 

-m Themaximum resident set size. 

-s Themaximum stack size. 

-t Themaximum amount of cpu time in seconds. 

-p Thepipesizein 512-byte blocks (Thismay not beset.) 

-n Themaximum number of open file descriptors (M ost systems 

do not allow thisvalueto beset, only displayed.) 

-u Themaximum numberof processes avai lableto a si ngle user. 

-v Themaximum amount of virtual memory availableto the 

shell. 

An argument of - disablesoption checking for the rest of the arguments. If limit is 
given, itisthenewvalueof the specified resource (the -a option is display only). If 
no option is given, then -f is assumed. Values are in 1024-byte increments, except 
for-t, which is in seconds; -p, which is in units of 512-byte blocks; and -n and -u, 
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which are unsealed values. The return status is 0 unless an illegal option is encoun¬ 
tered, a non-numeric argument other than unlimited is supplied as limit, or an error 
occurs while setti ng a new limit. 

umask [-S] [ mo d e ] T he user file-creation mask i s set to mo d e . If mode beginswith adigit, it is interpreted 

as an octal number; otherwise, it is interpreted asasymbolic modemask similar to 
that accepted by chmod(l). If mode is omitted, or if the-s option is supplied, the 
current value of the mask is printed. The-s option causes the mask to be printed in 
symbolic form; the default output is an octal number. An argument of - disables 
option checking for the rest of the arguments. The return status is 0 if the mode was 
successfully changed or if no mode argument was supplied, and False otherwise, 
unaiias [-a] [name ...] Remove names from the list of defi ned aliases. If -a is supplied, all alias definitions 

are removed. The return value ismue unless a supplied name is not a defined alias, 
unset [-fv] [name ...] For each name, remove the corresponding variable or, given the -f option, function. 

An argument of- disables option checking for the rest of thearguments. Note that 
path, ifs, ppid, psi, ps2, uid, and euid cannot be unset. If any of random, seconds, 
lineno, or histcmd are unset, they lose their special properties, even if they are 
subsequently reset. T he exit status is True unless a name does not exist or isnon- 
unsettable. 

wait [n ] W ait for the specified process and return its termination status, n may bea process 

ID or a job specification; if a job spec is given, all processes in that job's pipeline are 
waited for. If n is not given, all currently active child processes are waited for, and the 
return status is zero. If n specifies a nonexistent process or job, the return status is 
127. Otherwise the return status is the exit status of the last process or job waited 
for. 

INVOCATION 

A login shell is one whose first character of argument zero is a-, or one started with the -login flag. 

An interactive shell isonewhose standard input and output are both connected to terminals (as determined by isatty( 3 )), or 
one started with the-i option, psi is set and includes i if bash is interactive, allowing a shell script or a startup file to test this 
state. 

Login shells: 

On login (subject to the -noprofile option): 
if /etc/profile exists, source it. 
if '/.bash_profile exists, source it, 
else if "/.bash_login exists, source it, 
else if "/.profile exists, source it. 

On exit: 

if "/.bash_logout exists, source it. 

Non-login interactive shells: 

On startup (subject to the -norc and -refile options): 
if "/.bashre exists, source it. 

Non-interactive shells: 

On startup: 

if the environment variable ENV is non-null, expand 

it and source the file it names, as if the command 

if [ M $ENV" ]; then . $ENV; fi 

had been executed, but do not use PATH to search 

for the pathname. When not started in Posix mode, bash 

looks for BASH_ENV before ENV. 

If Bash is invoked assh, it tries to mimic the behavior of sh as closely as possible. For a login shell, it attempts to source only / 
etc/profiie and '/.profile, in that order. The-noprofiie option may still beused to disable this behavior. A shell invoked 
as sh does not attempt to source any other startup files. 
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When bash is started in posix mode, as with the-posix command line option, i t fol lows the PO SIX standard for startup files. 
In this mode theENv variable is expanded and that file sourced; no other startup files are read. 

SEE ALSO 

Bash Features, Brian Fox and Chet Ramey 

TheGnu ReadlineLibrary, Brian Fox and Chet Ramey 

TheGnu H i story Library, Brian Fox and Chet Ramey 

A System 1/ Compatible Implementation of4.2BSD Job Control, D avid Lennert 

P ortable Operating System I nterface (POSIX) Part 2: Shell and Utilities IEEE 

sh( 1 ), ksh(l), csh(l), emacs(l), vi( 1 ) readline( 3 ) 

FILES 

/bin/bash 
/etc/profile 
/ .bash_profile 
/.bashrc 
/.inputrc 

AUTHORS 

Brian Fox (Free Software Foundation; primary author; bfox@ai.Mu.Edu), Chet Ramey (Case Western Reserve University; 
chet@ins.CWRU.Edu) 

COPYRIGHT 

Copyright© 1989,1991 bytheFreeSoftwareFoundation, Inc. 

BUG REPORTS 

If you find a bug in bash, you should report it. But first, you should make sure that it really is a bug, and that it appears in 
the latest version of bash that you have. 

Once you have determined that a bug actually exists, mail a bug report to bash-maintainers@prep.ai.M IT.Edu. Ifyou havea 
fix, you are welcome to mail that as well I Suggestions and "philosophical" bug reports may be mailed to bug- 
bash@prep.ai.MIT.Edu Or posted to theU Senet newsgroup gnu.bash.bug. 

ALL bug reports should include the following: 

The version number of bash 
T he hardware and operating system 
Thecompiler used to compile 
A description of the bug behavior 
A short script or "recipe" that exercises the bug 

Comments and bug reports concerning this manual page should be directed to chet@ms.cwru.edu. 

BUGS 

It's too big and too slow. 

There are some subtle differences between bash and traditional versions of sh, mostly because of the posix specification. 
Aliases are confusing in some uses. 


The bash executable 

Thesystemwide initialization file, executed for login shells 
The personal initialization file, executed for login shells 
The individual per-interactive-shell startup file 
Individual readiine initialization file 


GNU, 9 March 1995 
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bdftopcf 

bdftopcf— Convert X font from Bitmap D istribution Format to Portable Compiled Format 

SYNOPSIS 

bdftopcf [ -pn ] [-un ][-m ][-1 ][-M ][-L ][-t ][-i ] [-0 out put fiI e ] fontfile.bdf 

DESCRIPTION 

bdftopcf is a font compiler for the x server and font server. Fonts in Portable Compiled Format can be read by any 

architecture, although the file is structured to allow one particular architecture to read them directly without reformatting. 

This allows fast reading on the appropriate machine, but the files are still portable (but read more slowly) on other machines. 

OPTIONS 

-pn Sets the font glyph padding. Each glyph in thefontwill have each scanline padded in to a multiple 

of n bytes, where n is 1, 2, 4, or 8. 

-un Sets the font scan line unit. W hen the font bit order is different from the font byte order, the 

scanline unit n describes what unit of data (in bytes) are to be swapped; the unit i can bel, 2, or4 
bytes. 

-m Sets the font bit order to msb (most significant bit) first. Bits for each glyph will be placed in this 

order; that is, the leftmost bit on the screen will be in the highest valued bit in each unit. 

-l Sets the font bit order to lsb (least significant bit) first. The leftmost bit on the screen will be in the 

lowest valued bit in each unit. 

-m Setsthefont byteorderto msb first. All multibyte data in thefile (metrics, bitmaps, and everything 

else) will be written most significant byte first. 

-l Setsthefont byteorderto lsb first. All multi byte data in thefile (metrics, bitmaps, and everything 

else) will be written least significant byte first. 

-t When this option is specified, bdftopcf will convert fonts into terminal fonts when possible A 

terminal font has each glyph image padded to the same size; thex server can usually render these 
types of fonts more quickly. 

-i This option inhibits the normal computation of ink metrics. When a font has glyph images that do 

not fill the bitmap image (that is, the "on" pixels don't extend to the edges of the metrics), bdftopcf 
computes the actual ink metrics and places them in thepcF file; the-t option inhibits this behavior. 

-o output-file-name By default bdftopcf writes thepcF file to standard output; this option givesthenameof a file to be 
used instead. 


SEE ALSO 

X(l) 

AUTHOR 

Keith Packard, M IT X Consortium 


X Version 11 Release 6 


beforelight 

beforeiight— Screen saver 

SYNOPSIS 

beforeiight [ -t ool ki t opt i on ... ] 
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DESCRIPTION 

The beforeiight program is a sample implementation of ascreen saver forx servers supporting theMu-scREEN-sAVER 
extension. 

AUTHORS 

Keith Packard (M IT X Consortium) 

X Version 11 Release 6 


biff 

biff— Be notified if mail arrives and who it is from 

SYNOPSIS 

biff [ny] 

DESCRIPTION 

biff in forms the system whether you want to be notified when mail arrives during the current terminal session. 

0 ptions supported by biff: 
n D isables notification 

y Enables notification 

When mail notification is enabled, the header and first few lines of the message will be printed on your screen whenever mail 
arrives. A 
biff y 

command is often included in the file .login or .profile to be executed at each login. 

Biff operates asynchronously. For synchronous notification use the mail variable of sh(l) or the mail variable of csh(l). 

SEE ALSO 

csh(l), mail(l), sh(l), comsat(8) 

HISTORY 

The biff command appeared in BSD 4.0. 

BSD 4,14 March 1991 


bioradtopgm 

bioradtopgm— Convert a Biorad confocal file into a portable gray map 

SYNOPSIS 

bioradtopgm [-image#] [i magedata ] 

DESCRIPTION 

Reads a Biorad confocal file as input. Produces a portable graymap as output. If the resulting image is upside down, run it 
through pnmflip -tb. 
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OPTIONS 

-image# A Biorad image file may contain more than oneimage. With thisflag, you can specify which image to 

extract (only one at a time). The first image in the file has number zero. If no image number is supplied, 
only information about the image size and the number of images in the input is printed out. N o output is 
produced. 

BUGS 

A Biorad image may be in word format. If PbmPius is not compiled with theBiGGRAYs flag, word files cannot be converted. See 

the makefile. 

SEE ALSO 

pgm(5), pnmflip(l) 

AUTHORS 

Copyright© 1993 by0liverTrepte 

28 Junel993 


bitmap,bmtoa,atobm 

bitmap, bmtoa, atobm— Bitmap editor and converter utilities for theX Window System 

SYNOPSIS 

bitmap [ -options ...][fi I ename ] [basename ] 
bmtoa [ -chars ... ] [f i I ename ] 


atobm [ -chars cc ][-name variable ][-xhot number ][-yhot number ][f i I e n a me ] 


DESCRIPTION 

The bitmap program is a rudimentary tool for creating or editing rectangular images made up of Is and Os. Bitmaps are used 
in x for defining clipping regions, cursor shapes, icon shapes, and tile and stipple patterns. 

The bmtoa and atobm filters convert bitmap files (file format) to and from ASCII strings. They are most commonly used to 
quickly print out bitmaps and to generate versions for including in text. 


COMMAND-LINE OPTIONS 


Bitmap supports the standard X T oolkit command-line arguments; see x(l). The following additional arguments are 
supported as well: 


-size Wl DTHx HE I GHT 
-sw di mensi on 
-sh di mensi on 
-gt di mensi on 

-grid, +grid 
-axes, +axes 
-dashed, +dashed 
-stippled, +stippled 


Specifies size of the grid in squares. 

Specifies the width of squares in pixels. 

Specifies the height of squares in pixels. 

Grid tolerance. If the square dimensions fall below the specified value, grid will be 
automatically turned off. 

T urns on or off thegrid lines. 

T urns on or off the major axes. 

T urns on or off dashing for the frame and grid lines. 

T urns on or off stippling of highlighted squares. 
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-proportional, +proportional 


-dashes f i I ename 
-stipple f i I ename 
-hi color 
-fr color 
filename 

basename 


T urns proportional mode on or off. If proportional modeison, squarewidth is 
equal to square height. If proportional mode is off, bitmap will use the smaller square 
di mensi on, if they were i n iti al ly different. 

Specifi es the bitmap to be used as a stipple for dashing. 

Specifies the bitmap to be used as a stipple for highlighting. 

Specifies the color used for highlighting. 

Specifies the color used for the frame and grid lines. 

Specifies the bitmap to be initially loaded into the program. If the file does not exist, 
bitmap will assume it is a new file. 

Specifies the basename to beused intheC code output file. If it is different than the 
basenamein the working file, bitmap will change it when saving thefile. 


bmtoa acceptsthefollowingoption: 

-chars cc This option specifies the pair of characters to use in the string version of the bitmap. 

The first character is used for 0 bits and the second character is used for 1 bits The 
default is to use dashes (-) for Os and number signs (#) for Is. 


atobm accepts thefollowing options: 
-chars cc 


-name vari abl e 


-xhot number 


-yhot number 


This option specifies the pair of characters to use when converting string bitmaps 
into arrays of numbers. The first character represents a 0 bit and the second 
character represents a 1 bit. The default is to use dashes (-) for Os and number signs 
(#) for Is. 

This option specifies the variable name to beused when writing out the bitmap file 
The default is to use the basename of the filename command-line argument or leave 
it blank if the standard input is read. 

This option specifies the X coordinate of the hot spot. 0 nly positive values are 
allowed. By default, no hotspot information is included. 

Thisoption specifies theY coordinateof the hot spot. Only positive values are 
allowed. By default, no hotspot information is included. 


USAGE 

bitmap displays grid in which each square representsa single bit in the picture being edited. Actual size ofthebitmap image, 
as it would appear normally and inverted, can be obtained by pressing M eta-l. You are free to move the image pop-up out of 
theway to continue editing. Pressing the I eft mouse button in the pop-up window or M eta-l again will remove the real size 
bitmap image. 

If the bitmap is to beused for defining a cursor, one of the squares in the images may be designated as the hot spot. This 
determines where the cursor is actually pointing. For cursors with sharp tips (such as arrows or fingers), this is usually at the 
end of the tip; for symmetric cursors (such as crosses or bulls-eyes), this is usually at the center. 

Bitmaps are stored as small C code fragments suitable for including in applications. They provide an array of bits as well as 
symbolic constants giving the width, height, and hot spot (if specified) that may beused in creating cursors, icons, and tiles. 

EDITING 

T o edit a bitmap image, simply click on one of the buttons with drawing commands (Point, Curve, Line, Rectangle, and so 
on) and move the pointer into the bitmap grid window. Press one of the buttons on your mouse and the appropriate action 
will take place. You can either set, clear, or invert the grid squares. Setting a grid square corresponds to setting a bit in the 
bitmap image to 1. Clearing a grid square corresponds to setting a bit in the bitmap image to 0. Inverting a grid square 
corresponds to changing a bit in the bitmap image from 0 to 1 or 1 to 0 , depending what its previous state was. The default 
behavior of mouse buttons is as follows: 
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MouseButtonl Set 
MouseButton2 Invert 
MouseButton3 Clear 
MouseButton4 Clear 
MouseButtonS Clear 

This default behavior can be changed by setting the button function resources. H ere is an example: 

bitmap*button1Function: Set 
bitmap*button2Function: Clear 
bitmap*button3Function: Invert 
etc. 

Thebutton function applies to all drawing commands, including copying, moving and pasting, flood filling, and setting the 
hot spot. 


DRAWING COMMANDS 


Here is the list of drawing commands accessible through the buttons at the left side of the application's window. Some 
commands can be aborted by pressing A inside the bitmap window, allowing the user to select different guiding points where 
applicable. 


Clear 
Set 
Invert 
M ark 


Unmark 

Copy 


M ove 


Flip Horizontally 


Up 


This command clears all bits in the bitmap image. The grid squares will beset to the 
background color. PressingC inside thebitmap window has the same effect. 

This command sets all bits in thebitmap image. The grid squares will beset to the 
foreground color. Pressing S inside the bitmap window has the same effect. 

This command inverts all bits in thebitmap image. The grid squares will be inverted 
appropriately. Pressing I inside the bitmap window has the same effect. 

This command is used to mark an area of the grid by dragging out a rectangular 
shape in the highlighting color. After the area is marked, it can be operated on by a 
number of commands (seeUp, Down, Left, Right, Rotate, Flip, Cut, and so on). 

0 nly one marked area can be present at any time. If you attempt to mark another 
area, the old mark will vanish. The same effect can be achieved by pressing Shift- 
M ouseButtonl and dragging out a rectangle in the grid window. Pressing Shift- 
M ouseButton2 will mark the entire grid area. 

Thiscommand will cause the marked area to vanish. The same effect can be 
achieved by pressing Shift-M ouseButton3. 

Thiscommand is used to copy an area of the grid from one location to another. If 
there is no marked grid area displayed, Copy behaves just like M ark. 0 ncethereisa 
marked grid area displayed in the highlighting color, thiscommand has two 
alternative behaviors. If you click a mouse button inside the marked area, you will be 
able to drag the rectangle that represents the marked area to the desired location. 
After you release the mouse button, the area will be copied. Ifyou click outside the 
marked area, Copy will assume that you wish to mark a different region of the 
bitmap image, thusitwill behavelikeM ark again. 

Thiscommand is used to move an area of the grid from one location to another. Its 
behavior resembles the behavior of Copy command, except that the marked area will 
be moved instead of copied. 

Thiscommand will flip thebitmap image with respect to the horizontal axes. If a 
marked area ofthegrid is highlighted, it will operate only inside the marked area. 
Pressing H inside the bitmap window has the same effect. 

Thiscommand moves the bitmap image one pixel up. If a marked area ofthegrid is 
highlighted, it will operate only inside the marked area. PressingUpArrow inside the 
bitmap window has the same effect. 
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Flip Vertically 

Left 

Fold 

Right 

Rotate Left 

Down 

Rotate Right 

Point 

Curve 

Line 

Rectangle 

Filled Rectangle 
Circle 

Filled Circle 
Flood Fill 


This command will flip the bitmap image with respect to the vertical axes. If a 
marked area of the grid is highlighted, it will operate only inside the marked area. 
Pressing V inside the bitmap window has the same effect. 

This command moves the bitmap image one pixel to the left. If a marked area of the 
grid is highlighted, itwill operate only inside the marked area. Pressing LeftArrow 
inside the bitmap window has the same effect. 

This command will fold the bitmap image so that the opposite corners become 
adjacent. This is useful when creating bitmap images for tiling. Pressing F inside the 
bitmap window has the same effect. 

This command moves the bitmap image one pixel to the right. If a marked area of 
thegrid is highlighted, itwill operate only inside the marked area. Pressing the right 
arrow inside the bitmap window has the same effect. 

This command rotates the bitmap image 90 degrees to the left (counterclockwise.) 

If a marked area of thegrid is highlighted, itwill operate only inside the marked 
area. Pressing L inside the bitmap window has the same effect. 

Thiscommand moves the bitmap imageone pixel down. If amarked area of thegrid 
ishighlighted, itwill operate only inside the marked area. Pressing the down arrow 
inside the bitmap window has the same effect. 

Thiscommand rotates the bitmap image 90 degrees to the right (clockwise.) If a 
marked area of thegrid ishighlighted, itwill operate only inside the marked area. 
Pressing R inside the bitmap window has the same effect. 

Thiscommand will change the grid squares underneath the mouse pointer if a 
mouse button is being pressed down. If you drag the mouse button continuously, 
the line may not be continuous, depending on the speed of your system and 
frequency of mouse motion events. 

Thiscommand will change the grid squares underneath the mouse pointer if a 
mouse button isbeing pressed down. If you drag the mouse button continuously, it 
will makesurethatthelineiscontinuous. Ifyour system isslow or bitmap receives 
very few mouse motion events, it might behavequite strangely. 

Thiscommand will change the grid squares in a line between two squares. 0 nee you 
press a mouse button in thegrid window, bitmap will highlight the line from the 
square where the mouse button was initially pressed to the square where the mouse 
pointer is located. By releasing the mouse button, you will cause the change to take 
effect, and the highlighted linewill disappear. 

Thiscommand will change the grid squares in a rectangle between two squares. 
Onceyou press a mouse button in thegrid window, bitmap will highlight the 
rectangle from the square where the mouse button was initially pressed to the square 
where the mouse pointer is located. By releasing the mouse button you will cause the 
change to take effect, and the highlighted rectangle will disappear. 

Thiscommand is identical to Rectangle, except at the end the rectangle will be filled 
rather than outlined. 

Thiscommand will change the grid squares in a circle between two squares. Once 
you press a mouse button in thegrid window, bitmap will highlight the circle from 
the square where the mouse button was initially pressed to the square where the 
mouse pointer islocated. By releasing the mouse button you will cause the change to 
take effect, and the highlighted circle will disappear. 

Thiscommand is identical to Circle except at the end the circle will be filled rather 
than outlined. 

This command will flood fill the connected area underneath the mouse pointer 
when you click on the desired square. D iagonally adjacent squares are not considered 
to be connected. 
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Set H ot Spot 


Clear H otSpot 
Undo 


This command designates one square in the grid as the hot spot if this bitmap image 
is to be used for defining a cursor. Pressing a mouse button in the desired square will 
cause a diamond shape to be displayed. 

This command removes any designated hot spot from the bitmap image. 

This command will undo the last executed command. It has depth one, that is, 
pressing Undo afterU ndo will undo itself. 


FILE MENU 

TheFilemenu commands can be accessed by pressing the File button and selecting the appropriate menu entry, or by 
pressing the Ctrl key with another key. These commands deal with files and global bitmap parameters, such assize, 
basename, filename, and so forth. 


N ew 
Load 


Insert 

Save 

Save As 
Resize 

Rescale 

Filename 

Basename 

Quit 


This command will clear the editing area and prompt for the name of the new file to 
be edited. It will not load in the new file. 

This command is used to load a new bitmap file into the bitmap editor. If the 
current image has not been saved, user will be asked whether to save or ignore the 
changes. The editor can edit only one file at a time If you need interactive editing, 
run anumber of editors and use the cut and paste mechanism as described laterin 
this section. (See "Cut and Paste”) 

This command is used to insert a bitmap file into the image being currently edited. 
After being prompted for the filename click inside thegrid window and drag the 
outlined rectangleto the location where you want to insert the new file. 

This command will save the bitmap image. It will not prompt for the filename 
unless it is said to be<none>. If you leave the filename undesignated or-, the output 
will be piped to stdout. 

This command will save the bitmap image after prompting for a new filename. It 
should be used if you want to change the filename. 

This command is used to resize the editing area to the new number of pixels. The 
size should be entered in the widthl height format. The information in theimage 
being edited will not be lost unless the new size issmaller that the current image size. 
T he editor was not designed to edit huge fi les. 

This command is used to rescale the editing area to the new width and height. The 
size should be entered in the widthl heightformat. It will not do antialiasing and 
information will be lost if you rescaleto the smaller sizes. Feel free to add you own 
algorithmsfor better rescaling. 

Thiscommand isused to change thefilenamewithout changing the basename nor 
saving the file. If you specify - for a filename, the output will be piped to stdout. 
Thiscommand isused to change the basename if a different one from the specified 
filename isdesired. 

Thiscommand will terminate the bitmap application. If the file was not saved, user 
will be prompted and asked whether to save the image or not. Quit is preferred over 
killing the process. 


EDIT MENU 

TheEditmenu commandscan be accessed by pressing the Edit button and selecting the appropriate menu entry, or by 
pressing M eta key with another key. These commands deal with editing facilities such as grid, axes, zooming, cut and paste, 
and so on. 

Image Thiscommand will display the image being edited and itsinversein its actual sizein 

a separate window. The window can be moved away to continue with editing. 
Pressing the I eft mouse button in theimage window will causeitto disappear from 
the screen. 
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Grid 

Thiscommand controls the grid in theediting area. If thegrid spacing isbelow the 
value specified by gridToierance resource (8 by default), thegrid will be automati¬ 
cally turned off. Itcan be enforced by explicitly activating thiscommand. 

Dashed 

Thiscommand controls the stipple for drawing thegrid lines. The stipple specified 
by dashes resource can be turned on or off by activating this command. 

Axes 

This command controls the highlighting of the mai n axes of the i mage bei ng edited. 
The actual lines are not part of the image. They are provided to aid user when 
constructing symmetrical images, orwhena/er havingthemain axes highlighted 
helps your editing. 

Stippled 

Thiscommand controls the stippling of the highlighted areas of the bitmap image. 
The stipple specified by stipple resource can be turned on or off by activating this 
command. 

Proportional 

Thiscommand controls the proportional mode. If the proportional modeison, 
width and height of all image squares are forced to be equal, regardless of the 
proportions of thebitmap window. 

Zoom 

Thiscommand controls the zoom mode. If there is a marked area of the image 
already displayed, bitmap will automatically zoom into it. Otherwise, the user will 
have to highlight an area to be edited in the zoom mode and bitmap will automati¬ 
cally switch into it. You can use all the editing commands and other utilities in the 
zoom mode. W hen you zoom out, undo command will undo thewholezoom 


session. 

Cut 

This commands cuts the contents of the highlighted image area into the internal cut 
and paste buffer. 

Copy 

Thiscommand copies the contents of the highlighted image area into the internal 
cut and paste buffer. 

Paste 

Thiscommand will check if there are any other bitmap applications with a 
highlighted image area, or if there is something in the internal cut and paste buffer 
and copy it to the image. T o pi ace the copied image, click in the editing window and 
drag the outlined image to the position where you wantto placei, and then release 
the button. 


CUT AND PASTE 

Bitmap supports two cut and paste mechanisms; the internal cut and paste and the global X selection cut and paste. The 
internal cut and paste is used when executing copy and move drawing commands and also cut and copy commands from the 
Edit menu. The global X selection cut and paste is used whenever there is a highlighted area of a bitmap image displayed 
anywhere on the screen. To copy a part of image from another bitmap editor, simply highlight the desired area by using the 
M ark command or pressing the shift key and dragging the area with the left mouse button. When the selected area becomes 
highlighted, any other applications (such asxterm) that use primary selection will discard their selection values and 
unhighlight the appropriate information. N ow, use the Paste command from the Edit menu or control mouse button to 
copy the selected part of image into another (or the same) bitmap application. If you attempt to do this without a visible 
highlighted image area, thebitmap will fall back to the internal cut and paste buffer and paste whatever was stored thereat 
the moment. 

WIDGETS 

Following is the widget structure of the bitmap application. The widget class name is given first, followed by the widget 
instance name. All widgets except thebitmap widget are from the standard Athena widget set. 

Bitmap bitmap 
TransientShell image 
Box box 

Label normallmage 
Label invertedlmage 
TransientShell input 
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Dialog dialog 
Command okay 
Command cancel 
TransientShell error 
Dialog dialog 
Command abort 
Command retry 
TransientShell qsave 
Dialog dialog 
Command yes 
Command no 
Command cancel 
Paned parent 
Form formy 

MenuButton fileButton 
SimpleMenu fileMenu 
SmeBSB new 
SmeBSB load 
SmeBSB insert 
SmeBSB save 
SmeBSB saveAs 
SmeBSB resize 
SmeBSB rescale 
SmeBSB filename 
SmeBSB basename 
SmeLine line 
SmeBSB quit 
MenuButton editButton 
SimpleMenu editMenu 
SmeBSB image 
SmeBSB grid 
SmeBSB dashed 
SmeBSB axes 
SmeBSB stippled 
SmeBSB proportional 
SmeBSB zoom 
SmeLine line 
SmeBSB cut 
SmeBSB copy 
SmeBSB paste 
Label status 
Pane pane 
Bitmap bitmap 
Form form 
Command clear 
Command set 
Command invert 
Toggle mark 
Command unmark 
Toggle copy 
Toggle move 
Command flipHoriz 
Command up 
Command flipVert 
Command left 
Command fold 
Command right 
Command rotateLeft 
Command down 
Command rotateRight 
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Toggle point 
Toggle curve 
Toggle line 
Toggle rectangle 
Toggle filledRectangle 
Toggle circle 
Toggle filledCircle 
Toggle floodFill 
Toggle setHotSpot 
Command clearHotSpot 
Command undo 

COLORS 

If you would like bitmap to be viewable in color, include the foil owing in the#ifdef color section of the file you read with 
xrdb: 

*customization: -colon 

This will cause bitmap to pick up the colors in the app-defaults color customization file 

<XRoot>/lib/X11/app-defaults/Bitmap-color 

where <xRoot> refers to theroot of theXll install tree. 

BITMAP WIDGET 

Bitmap widget is a standalone widget for editing raster images. It is not designed to edit large images, although it may be 
used in that purpose as well. It can be freely incorporated with other applications and used as a standard editing tool. The 
following are the resources provided by the bitmap widget: 

Header file Bitmap, h 

Class bitmapWidgetClass 

Class Name Bitmap 

Superclass Bitmap 

All the Simple W idget resources plus... 


Name 

Class 

Type 

Default Value 

foreground 

Foreground 

Pixel 

XtD efaultForeground 

highlight 

H ighlight 

Pixel 

XtD efaultForeground 

framing 

Framing 

Pixel 

XtD efaultForeground 

gridT olerance 

GridT olerance 

D imension 

8 

size 

Size 

String 

32x32 

dashed 

Dashed 

Boolean 

T rue 

grid 

Grid 

Boolean 

T rue 

stippled 

Stippled 

Boolean 

T rue 

proportional 

Proportional 

Boolean 

T rue 

axes 

Axes 

Boolean 

False 

squareWidth 

SquareWidth 

D imension 

16 

squareH eight 

SquareH eight 

D imension 

16 

margin 

M argin 

D imension 

16 

xH ot 

XH ot 

Position 

NotSet(-l) 

yH ot 

YH ot 

Position 

NotSet(-l) 

buttonlFunction 

ButtonlFunction 

D rawingFunction 

Set 
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Name Class Type Default Value 


button2Function 

Button2Function 

D rawingFunction 

Invert 

button3Function 

Button3Function 

D rawingFunction 

Clear 

button4Function 

Button4Function 

D rawingFunction 

Invert 

button5Function 

Button5Function 

D rawingFunction 

Invert 

filename 

Filename 

String 

N one("") 

basename 

Basename 

String 

N one ("") 

AUTHOR 




D avor M atic (M IT X C onsortium) 




X Version 11 Release 6 


bmptoppm 

bmptoppm— Convert a BM P file into a portablepixmap 

SYNOPSIS 

bmptoppm [bmpfile] 

DESCRIPTION 

bmptoppm reads a M icrosoft W indowsor OS/2 BMP file as input and produces a portable pixmap as output. 

SEE ALSO 

ppmtobmp(l), ppm(5) 

AUTHOR 

C opyright © 1992 by D avid W. Sanderson 

26 October 1992 


brushtopbm 

brushtopbm— C onvert a doodle brush file into a portable bitmap 

SYNOPSIS 

brushtopbm [br ushfiI e ] 

DESCRIPTION 

brushtopbm reads a Xerox doodle brush fi le as input and produces a portable bitmap as output. 
N otethat there is currently no pbmtobrush tool. 

SEE ALSO 

pbm(5) 

AUTHOR 

Copyright© 1988 byjef Poskanzer 


28 Augu$1988 
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cal 

cai— D i splays a calendar 

SYNOPSIS 

cal [-jy] [month [year ]] 

DESCRIPTION 

cai displays a simple calendar. If arguments are not specified, the current month is displayed. The options are as follows: 

-j D isplayjulian dates (days one-based, numbered fromjanuary 1) 

-y D i splay a calendar for the current year 

A single parameter specifies the year (1-9999) to be displayed; note the year must be fully specified: 

cal 89 

will not display a calendar for 1989. T wo parameters denote the month (1-12) and year. If no parameters are specified, the 
current month's calendar is displayed. 

A year starts on Jan 1. 

The Gregorian Reformation is assumed to have occurred in 1752 on the 3rd of September. By this time, most countries had 
recognized the reformation (although a few did not recognize it until the early 1900s.) T en days following that date were 
eliminated by the reformation, so the calendar for that month is a bit unusual. 

HISTORY 

A cai command appeared in version 6 AT&T UNIX 

6 Junel993 


cat 

cat— Concatenate files and print on the standard output 

SYNOPSIS 

cat [-benstuvAET] [—number] [ — number-nonblank] [-squeeze-blank] 


[-show-nonprinting] [-show-ends] [-show-tabs] [-show-all] 


[—help] [ — version] [file...] 


DESCRIPTION 

This manual page documents the GN U version of cat. cat writes the contents of each given file, or the standard input if 
none are given or when a file named - is given, to the standard output. 


OPTIONS 

-b, —number-nonblank 
-e 

-n, —number 

-s, -squeeze-blank 

-t 

-u 


N umber all nonblank output lines, starting with 1. 
Equivalentto -vE. 

Number all output lines, starting with 1. 

Replace multiple adjacent blank lines with a single blank line. 
Equivalentto -vr. 

Ignored; for UN IX compatibility. 
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-v, -show-nonprinting 

-A, —show-all 
-E, -show-ends 
-T, -show-tabs 

— help 

— version 


D isplay control characters except for lfd and tab using ■ notation and precede characters that 
havethehigh bit set with m-. 

Equivalentto -vet. 

D isplay a $ after the end of each line 
D isplay tab characters as "i. 

Print a usage message and exit with a nonzero status. 

Print version information on standard output then exit. 

GNU Text Utilities 


chattr 

chattr— Change file attributes on a Linux second extended file system 

SYNOPSIS 

chattr [ -RV ][-v version ] [ mode ] files... 

DESCRIPTION 

chattr changes the files attributes on an second extended filesystem. Theformat of asymbolic modeis + -=[Sacdisuj. 

The operator + causes the selected attributes to be added to the existing attributes of the files; ■ causes them to be removed; 
and = causes them to be the only attributes that the files have. The letters sacdisu select the new attributes for the files: 
synchronous updates (s), append only (a), compressed (x), immutablefi), nodump (d), securedeletion (s), and undeletable 
(u). 

OPTIONS 

-R Recursively change attributes of directories and their contents 

-v Verbosely describe changed attributes. 

-v version Set the file's version. 

ATTRIBUTES 

A filewith the a attribute set can only be open in append mode for writing. 

A filewith thee attribute set is automatically compressed on the disk by the kernel. A read from this file returns 
uncompressed data. A write to thisfile compresses data before storing them on the disk. 

A filewith the d attribute set is not candidate for backup when the dump(8) program isrun. 

A filewith the i attribute cannot be modified: it cannot be deleted or renamed, no link can be created to thisfile and no data 
can be written to the file. Only the superuser can set or clear this attribute. 

When afilewith thes attribute set is deleted, its blocks are zeroed and written back to the disk. 

When afilewith theu attribute set is modified, the changes are written synchronously on the disk; this is equivalent to the 
syn 1 mount option applied to a subset of the files. 

When afilewith theu attribute set is deleted, its contents is saved. This allows the user to ask for its undeletion. 

AUTHOR 

chattr has been written by Remy Card, <cardiamasi.ibp.fr>, the developer and maintainer of theext 2 fs. 

BUG SAND LIMITATIONS 

As of ext 2 f s 0.5a, the c and u attributes are not honored by the kernel code. 

These attributes will beimplemented in afutureext 2 fs version. 
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AVAILABILITY 

chattr is available for anonymous ftp from ftp.ibp.fr and tsx -11 .mit.edu in /pub/linux/packages/ext 2 f s. 

SEE ALSO 

lsattr(l) 

Version 0.5b, N ovember!994 


chfn 

chfn — C hange your finger information 

SYNOPSIS 

chfn [ -f full-name ][-o office] [-p office-phone ] [ -h home-phone ] [ -u ] [ -v ] 

[ u s e r n a me ] 

DESCRIPTION 

chfn isused to change your finger information. This information is stored in the/etc/passwd file, and isdisplayed by the 
finger program. T he Linux finger command will display four pieces of information that can be changed by chfn: your real 
name, your work room and phone, and your home phone. 

COMMAND LINE 

Any of the four pieces of information can be specified on the command line. If no information is given on the command 
line chfn enters interactive mode. 

INTERACTIVE MODE 

In interactive mode, chfn will prompt for each field. At a prompt, you can enter the new information, or just press return to 
leave the field unchanged. Enter the keyword none to makethefield blank. 


OPTIONS 


-f, -full-name 

Specify your real name. 

-o, —office 

Specify your office room number. 

-p, -office-phone 

Specify your office phone number. 

-h, -home-phone 

Specify your home phone number. 

-u, —help 

Print a usage message and exit. 

-v, —version 

Print version information and exit. 

SEE ALSO 


finger(l), passwd(5) 



AUTHOR 

Salvatore Valente (<svalente@mit .edu>) 


chfn, October 13 1994 
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chgrp 

chgrp— Change the group ownership of files 

SYNOPSIS 

chgrp [-Rcfv] [—recursive] [—changes] [—silent] [—quiet] [—verbose] [—help] 

[ —version] group file... 

DESCRIPTION 

This manual page documents the GN U version of chgrp. chgrp changes the group ownership of each given file to the named 
group, which can be either a group nameor a numeric group ID. 

OPTIONS 

-c, -changes 
-f, —silent, —quiet 
-v, —verbose 
-R, —recursive 

— help 

— version 

chkdupexe 

chkdupexe — Find duplicate executables 

SYNOPSIS 

chkdupexe 

DESCRIPTION 

chkdupexe will scan many standard directories that hold executable, and report duplicates. 

AUTHOR 

N icolai Langfeldt 

BUGS 

RequiresGNU is(l). 

Search paths that point to the same directory will cause many bogus duplicates to be found. You might want to edit the 
script to eliminate some paths that are equivalent on your machine. 

11 March 1995 


Verboselydescribeonlyfileswhoseown ersh i p actual I y ch an ges. 

Do not print error messages about files whose ownership cannot be changed. 

V erbosel y descri be own ersh i p ch anges. 

Recursively change ownership of di rectories and their contents. 

Print a usage message on standard output and exit successfully. 

Print version information on standard output, then exit successfully. 

GNU FileUtilities 


chmod 

chmod— C hange the access permissions of files 

SYNOPSIS 


chmod [-Rcfv] [—recursive] [—changes] [—silent] [—quiet] [—verbose] [—help] 
[ —version] mode file... 
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DESCRIPTION 

This manual page documents the GN U version of chmod. chmod changes the permissions of each given file according to mode, 
which can be either a symbolic representation of changes to make, or an octal number representing the bit pattern for the 
new permissions. 

The format of a symbolic mode is [ugoa. ..][[+-=][rwxxstugo. .M ulti pie symbolic operations can be given, 
separated by commas. 

A combination of the letters ugoa controls which users' access to the file will be changed: the user who owns it (u), other users 
in the file's group (g), other users not in the file's group (o), or all users (a). If none of these are given, the effect is as if a were 
given, but bits that are set in theumask are not affected. 

The operator + causes the permissions selected to be added to the existing permissions of each file; - causes them to be 
removed; and = causes them to be the only permissions that the file has. 

The letters rwxxstugo select the new permissions for the affected users: read (r), write (w), execute (or access for directories) 

(x), execute only if the file is a directory or already has execute permission for some user (x), set user or group ID on 
execution (s), save program text on swap de/ice (t), the permissions that the user who owns the file currently has for it (u), 
the permissions that other users in thefile's group have for it (g), and the permissions that other users notin the file's group 
have for it (o). 

A numeric mode is from one to four octal digits (0-7), derived by adding up the bits with values 4, 2, and 1. Any omitted 
digits are assumed to be leading zeros. The first digit selectstheset user ID ( 4 ) and set group ID ( 2 ) and save text image ( 1 ) 
attributes. The second digit selects permissionsfor the user who ownsthefile: read ( 4 ), write ( 2 ), and execute(i); thethird 
selects permissions for other users in thefile's group, with the same values; and the fourth for other users not in thefile's 
group, with the same values. 

chmod never changes the permissions of symbolic links; the chmod system call cannot change their permissions. This is not a 
problem si nee the permissions of symbolic links are never used. H owever, for each symbolic link listed on the command line, 
chmod changes the permissions of the pointed-to file. In contrast, chmod ignores symbolic links encountered during recursive 
directory traversals. 

OPTIONS 

-c, —changes 
-f, —silent, —quiet 
-v, —verbose 
-R, —recursive 

— help 

— version 

GNU FileUtilities 


Verbosely describe only files whose permissions actually change. 

D 0 not print error messages about files whose permissions cannot be changed. 
Verbosely describe changed permissions. 

Recursively change permissions of directories and their contents. 

Print a usage message on standard output and exit successfully. 

Print version information on standard output, then exit successfully. 


chown 

chcwn— Change the user and group ownership of files 

SYNOPSIS 


chcwn [-Rcfv] [—recursive] [ — changes] [-help] [-versicn] [—silent] [-quiet] 
[-verbese] [user ][:.][group] file... 



chsh 



DESCRIPTION 

This manual page documents the GN U version of chown. chown changes the user and/or group ownership of each given file, 
according to its first nonoption argument, which is interpreted as follows. If only a username (or numeric user ID) is given, 
that user is made the owner of each given file, and the files' group is not changed. If the username is followed by a colon or 
dot and a group name (or numeric group ID), with no spaces between them, the group ownership of the files is changed as 
well. If a colon or dot but no group name follows the username that user is made the owner of the files and the group of the 
files is changed to that user's login group. If the colon or dot and group are given, but the username is omitted, only the 
group of thefilesischanged; in thiscase, chown performsthe same function aschgrp. 

OPTIONS 

-c, —changes 
-f, —silent, —quiet 
-v, —verbose 
-R, —recursive 

— help 

— version 

GNU FileUtilities 


Verboselydescribeonlyfileswhoseown ersh i p actual I y ch an ges. 

Do not print error messages about files whose ownership cannot be changed. 
Verbosely describe ownership changes. 

Recursively change ownership of directories and their contents. 

Print a usage message on standard output and exit successfully. 

Print version information on standard output then exit successfully. 


chsh 

chsh— Change your login shell 

SYNOPSIS 

chsh [ -s shell ] [ -1 ] [ -u ] [ -v ] [ username ] 


DESCRIPTION 

chsh is used to change your login shell. If a shell is not given on the command line, chsh prompts for one. 

VALID SHELLS 

chsh will accept thefull pathname of any executable file on the system. However, itwill issue a warning if the shell isnot 
listed in the /etc/sheiis file 


OPTIONS 

-s, —shell 
-1, -list-shells 
-u, —help 
-v, —version 


Specify your login shell. 

Print the list of shells listed in /etc/sheiis and exit. 
Print a usage message and exit. 

Print version information and exit. 


SEE ALSO 

login(l), passwd(5), shells(5) 

AUTHOR 

Salvatore Valente (<svalente@mit. edu>) 


chsh, 13 October 1994 
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ci 

ci— Check in RCS revisions 

SYNOPSIS 

ci [options] file ... 

DESCRIPTION 

ci stores new revisions into RCS files. Each pathname matching an RCS suffix is taken to bean RCS file. All others are 
assumed to be working files containing new revisions, ci deposits the contents of each working file into the corresponding 
RCS file. If only a working file is given, ci tries to find the corresponding RCS file in an RCS subdirectory and then in the 
working file’s directory. (For more details, see "File N aiming,” later in this manual page.) 

For ci to work, the caller's login must be on the access list, unless the access list is empty or the caller is the superuser or the 
owner of the file T o append a new revision to an existing branch, the tip revision on that branch must be locked by the 
caller. Otherwise, only anew branch can be created. This restriction is not enforced for the owner of the file if non-strict 
locking is used; seercs(l). A lock held by someone else can be broken with the res command. 

Unlessthe-f option is given, ci checks whether the revision to be deposited differs from the preceding one. If not, instead of 
creating a new revision ci reverts to the preceding one. T o revert, ordinary ci removes the working file and any lock; ci - I 
keeps and ci -u removes any lock, and then they both generatea new workingfilemuch as if co -1 or co -u had been applied 
to the preceding revision. When reverting, any-n and -s options apply to the preceding revision. 

For each revision deposited, ci prompts for a log message. The log message should summarize the change and must be 
terminated by end-of-fileorbyalinecontaining . by itself. If several files are checked in, ci asks whether to reuse the 
previous log message. I f the standard input is not a terminal, ci suppresses the prompt and usesthesamelog message for all 
files. (Seealso -m.) 

If the RCS file does not exist, ci creates it and deposits the contents of the working file as the initial revision (default 
number: i . 1 ). The access list is initialized to empty. Instead of the log message, ci requests descriptive text (See-t.) 

The number rev of the deposited revision can be given by any of the options -f, -i, - 1 , -j, -k, - 1 , -m, -q, -r, or -u. rev can be 
symbolic, numeric, or mixed. Symbolic names in rev must already be defined; see the -n and -n options for assigning names 
during checkin. If rev is $, ci determines the revision number from keyword values in the working file. 

If rev begins with a period, then the default branch (normally the trunk) is prepended to it. If rev is a branch number 
followed by a period, then the latest revision on that branch is used. 

If rev is a revision number, it must be higher than the latest one on the branch to which rev belongs, or must start a new 
branch. 

If rev is a branch rather than a revision number, the new revision is appended to that branch. The level number is obtained 
by incrementing the tip revision number of that branch. If rev indicates a nonexistent branch, that branch is created with the 
initial revision numbered rev.i. 

If rev is omitted, ci tries to derive the new revision number from the caller's last lock. If the caller has locked the tip revision 
of a branch, the new revision is appended to that branch. The new revision number is obtained by incrementing the tip 
revision number. If the caller locked a nontip revision, a new branch is started at that revision by incrementing the highest 
branch number at that revision. The default initial branch and level numbers are 1 . 

If rev is omitted and the caller has no lock, but owns the file and locking is not set to strict, then the revision is appended to 
the default branch. (N ormally the trunk; seethe-b option of rcs(l).) 

Exception: On the trunk, revisions can be appended to the end, but not inserted. 
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-rrev Check in revision rev. 

-r The bare -r option (without any revision) has an unusual meaning in ci. With other RCS 

commands, a bare -r option specifies the most recent revision on the default branch, but with ci, a 
bare -r option reestablishes the default behavior of releasing a lock and removing the working file, 
and is used to override any default -1 or -u options established by shell aliases or scripts. 

-l [ r e v ] Works like -r, except it performs an additional co -1 for the deposited revision. Thus, the 

deposited revision is immediately checked out again and locked. This is useful for saving a revision 
although onewants to continue editing it after the checkin. 

-u [ r e v ] Works like - 1 , except that the deposited revision is not locked. This lets one read the working file 

immediately after checkin. 

The-i, bare -r, and -u options are mutually exclusive and silently override each other. For example, ci -u -r is equivalent 
to ci -r because bare -r overrides -u. 

-f [rev] Forces a deposit; the new revision is deposited even it is not different from the preceding one. 

-k [ r e v ] Searches the working file for keyword values to determine its revision number, creation date, state, 

and author— see co(l)— and assigns these values to the deposited revision, rather than computing 
them locally. It also generates a default login message noting the login of the caller and the actual 
checkin date. Thisoption isuseful for software distribution. A revision that issentto several sites 
should be checked in with the-k option at these sites to preserve the original number, date, author, 
and state. T he extracted keyword values and the default log message can be overridden with the 
options-d, -in, -s, -w, and any option that carries a revision number. 

-q [rev] Quiet mode; diagnostic output is not printed. A revision that is not different from the preceding 

one is not deposited, unless-t is given. 

- i [ r e v ] Initial checkin; report an error if the RCS file already exists. This avoids race conditions in certain 

applications. 

-j [ r e v ] Just check in and do not initialize; report an error if the RCS file does not already exist. 

- 1 [r ev] Interactive mode; the user is prompted and questioned even if the standard input is not a terminal, 

-d [d a t e ] U ses date for the checkin date and time. The date is specified in free format as explained in co(l). 

This is useful for lying about the checkin date, and for -k if no date is avail able If date is empty, 
the working file's time of last modification is used. 

-m [rev] Set the modification time on any new working fileto be the date of the retrieved revision. For 

example, ci -d -m -u t does not alter t's modification time, even if t's contents change due to 
keyword substitution. U sethisoption with care; it can confusemake(l). 

-mmsg U ses the stri ng ms g asthelog message for all revisions checked in. By convention, log messages that 

start with # are comments and are ignored by programs like G N U emacs’svc package. Also, log 
messages that start with ciumpname (followed by whitespace) aremeantto be clumped together if 
possible, even if they are associated with different files; the ciumpname label is used only for 
clumping, and is not considered to be part of the log message itself. 

-nname Assigns the symbolic name to the number of the checked-in revision, ci prints an error message if 

that name is already assigned to another number. 

-Nname Sameas-n, except that it overrides a previous assignment of name. 

-sstate Sets the state of the checked-in revision to the identifier state. T he default state is Exp. 

-tf i i e Writes descriptive text from the contents of the named file into the RCS file deleting the existing 

text. Thefilecannot begin with -. 

-t-stri ng W rite descriptive text from thestring into the RCS file deleting the existing text. 

The-t option, in both its forms, has effect only during an initial checkin; it is si lently ignored otherwise. 

During the initial checkin, if-t is not given, ci obtains the text from standard input, terminated by end-of-fileor by a line 
contai n i ng a dot (.) by itself. The user is prompted for the text if interaction is possible; see-i. 
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For backwards compatibility with older versionsof RCS, abare-t option isignored. 

Set the RC S file's modification time to the new revision's time if the former precedes the latter and 
there is a new revision; preserve the RCS file's modification time otherwise. If you have locked a 
revision, ci usually updates the RCS file's modification time to the current time, because the lock is 
stored in the RCS file and removing the lock requires changing the RCS file. This can create an 
RCS file newer than theworkingfilein one of two ways: first, ci -m can create a working file with 
a date before the current time; second, when reverting to the previous revision the RCS file can 
change whiletheworking file remains unchanged. These two cases can cause excessive 
recompilation caused by amake(l) dependency of the working file on the RCS file. The -t option 
inhibits this recompilation by lying about the RCS file's date. U sethis option with care; it can 
suppress recompilation even when a checkin of oneworkingfileshould affect another working file 
associated with the same RCS file. For example, suppose the RCS file's time is 01:00, the (changed) 
working fi le's time is 02:00, some other copy of the working fi le has a time of 03:00, and the 
current time is 04:00. Then ci-d -T sets the RCS file's time to 02:00 instead of the usual 04:00; 
this causes make(l) to think (incorrectly) that the other copy is newer than the RCS file. 

Uses login for the author field of the deposited revision. U seful for lying about the author, and for 
-k if no author is available. 

Print RCS's version number. 

EmulateRCSversion n. Seeco(l) for details. 

Specifies the suffixes for RCS files. A nonempty suffix matches any pathnameending in the suffix. 
An empty suffix matches any pathname of the form Rcs/path or pathi/Rcs/path2. The-x option 
can specify a list of suffixes separated by /. For example -x,v/ specifies two suffixes: ,v and the 
empty suffix. If two or more suffixes are specified, they are tried in order when looking for an RCS 
file; the first one that works is used for that file. If no RCS file is found but an RCS file can be 
created, the suffixes are tried in order to determine the new RCS file's name The default for 
suffixes is installation-dependent; normally It is, v/ for hosts like U NIX that permit commas in 
filenames, and is empty (that is, just the empty suffix) for other hosts. 

Specifies the date output format in keyword substitution, and specifiesthe default time zonefor 
date in the-ddate option. The zone should be empty, a numeric UTC offset, or the special string 
lt for local time. The default is an empty zone, which uses the traditional RCS format of UTC 
without any time-zone indication and with slashes separating the parts of the date; otherwise, times 
are output in ISO 8601 format with time zone indication. For example, if local timeisjanuary 11, 
1990, 8 p.m. Pacific Standard Time eight hours west of UTC, then the time is output as follows: 

Option Time Output 

-z 1990/01/12 04:00:00 (default) 

-zLT 1990-01-11 20:00:00-08 

-z+05:30 1990-01-12 09:30:00+05:30 

The-z option does not affect dates stored in RCS files, which are always UTC. 

FILE NAMING 

Pairs of RCS files and working files can be specified in three ways. (See also "Examples," next.) 

1. Both the RCS file and the working file are given. The RCS pathname is of the form pathi/worktiiex and the working 
pathname is of the form path2/workfiie where pathi / and path2/ are (possibly different or empty) paths, worktiie is a 
filename and x is an RCS suffix. If x is empty, pathi / must start with rcs / or must contain /rcs/. 

2. Only the RCS file is given. Then theworking file is created in the current directory and its name is derived from the 
name of the RC S file by removing pathi / and the suffix x. 


-wl ogi n 

-V 

-Vn 

-xsuf f i xes 




0 



3. Only theworking file is given. Then ci considers each RC S suffix X in turn, lookingforan RCS file of the form path2/ 
Ftcs/workf ilex or (if the former is not found and x is nonempty) path2/workfiiex. 

If the RCS file is specified without a path in one of the first two preceding scenarios, ci looks for the RCS file first in the 
directory ,/rcs and then in the current directory. 

ci reports an error if an attempt to open an RCS file fails for an unusual reason, even if the RCS file's pathname is just one 
of several possibilities. For example, to suppress use of RCS commands in a directory d, create a regular file named d/Rcs so 
that casual attempts to use RCS commands in d fail because d/Rcs is not a directory. 

EXAMPLES 

Suppose ,v is an RCS suffix and the current directory contains a subdirectory RCS with an RCS file io.c.v. Then each of 
the following commands checks in a copy of io.c into Rcs/io.c,v as the latest revision, removing io.c: 

ci io.c; ci RCS/io.c,v; ci io.c,v; 
ci io.c RCS/io.c,v; ci io.c io.c,v; 
ci RCS/io.c,v io.c; ci io.c,v io.c; 

Suppose instead that the empty suffix is an RC S suffix and the current directory contains a subdirectory RCS with an RC S 
file io.c.Then each of the following commands checks in anew revision: 

ci io.c; ci RCS/io.c; 
ci io.c RCS/io.c; 
ci RCS/io.c io.c; 

FILE MODES 

An RCS file created by ci inherits the read and execute permissions from theworking file If the RCS file exists already, ci 
preserves its read and execute permissions ci always turns off all write permissions of RCS files. 

FILES 

T emporary files are created in the directory containing the working file, and also in the temporary directory. (See tmpdir 
under "Environment.") A semaphore file or files are created in the directory containing the RCS file. With a nonempty 
suffix, the semaphore names begin with the first character of the suffix; therefore, do not specify an suffix whose first 
character could be that of a working filename. With an empty suffix, the semaphore names end with an underscore (_), so 
working filenames should not end in _. ci never changes an RCS or working file. N ormally, ci unlinks the file and creates a 
new one; but instead of breaking a chain of one or more symbolic links to an RCS file, it unlinks the destination file instead. 
Therefore ci breaks any hard or symbolic links to any working file it changes; and hard links to RCS files are ineffective, but 
symbolic links to RCSfilesare preserved. 

The effective user must be able to search and write the directory containing the RCS file. N ormally, the real user must be 
able to read the RCS and working files and to search and write the directory containing theworking file; however, some 
older hosts cannot easily switch between real and effective users, so on these hosts the effective user is used for all accesses. 
The effective user is the same as the real user unless your copies of ci and co havesetuid privileges. These privileges yield 
extra security if the effective user owns all RCS files and directories, and if only the effective user can write RCS directories. 

Users can control access to RCS files by setting the permissions of the directory containing the files; only users with write 
access to the directory can use RCS commands to change its RCS files. For example, in hosts that allow a user to belong to 
several groups, one can make a group's RCS directories writable to that group only. This approach suffices for informal 
projects, but it means that any group member can arbitrarily change the group's RCS files, and can even remove them 
entirely. Hence, more formal projects sometimes distinguish between an RCS administrator, who can change the RC S files 
at will, and other project members, who can check in new revisions but cannot otherwise change the RCS files. 

setuidUSE 

T o prevent anybody but their RCS administrator from deleting revisions, a set of users can employ setuid privileges as 
follows: 
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■ C heck that the host supports RC S setuid use. C onsult a trustworthy expert if there are any doubts. It is best if the 
setuid system cal Is works as described in POSIX 1003.1a D raft 5, because RCS can switch back and forth easily 
between real and effective users, even if the real user is root. If not, the second best is if the setuid system call supports 
saved setuid (the{_Posix_sAVED_iDS} behavior of POSIX 1003.1-1990); this fails only if the real or effective user is root. 
If RCS detects any failure in setuid, it quits immediately. 

■ Choose a user A to serve as RCS administrator for the set of users. Only A can invoke the res command on the users' 
RCS files. A should not be root or any other user with special powers. M utually suspicious sets of users should use 
different administrators. 

■ C hoose a pathname B to be a directory of files to be executed by the users. 

■ H aveA set up B to contain copies of ci and co that are setuid to A by copying the commands from their standard 
installation directory D asfollows: 

mkdir B cp D/c[io] B chmod go-w,u+s B/c[io] 

■ H aveeach user prepend B to his/her path asfollows: 

PATH=B:$PATH; export PATH # ordinary shell 
set path=(B $path) # C shell 

■ H aveA create each RCS directory R with write access only to A asfollows: 
mkdir R chmod go-w R 

■ If you want to let only certain users read the RCS files, put the users into a group G, and have A further protect the RCS 
directory asfollows: 

chgrp G Rchmod g-w,o-rwx R 

■ HaveA copy old RCS files (if any) into R, to ensure that A owns them. 

■ An RCS file's access list limits who can check in and lock revisions. The default access list is empty, which grants 
checkin access to anyone who can read the RCS file If you want limit checkin access, have A invoke res -a on the file; 
see rcs(l). In particular, res -e -aA limits access to just A. 

■ H aveA initialize any new RCS files with res -i before initial checkin, adding the -a option if you want to limit checkin 
access. 

■ Give setuid privileges only to ci, co, and rcsciean; do not give them to res or to any other command. 

■ Do not use other setuid commands to invoke RCS commands; setuid istrickier than you think! 

ENVIRONMENT 

rcsinit Options prepended to theargument list, separated by spaces. A backslash escapes spaces within an option. 

T he rcsinit options are prepended to theargument lists of most RCS commands. Useful rcsinit options 
include -q, -v, -x, and -z. 

tmpdir N ame of the temporary directory. If not set, the environment variablesTMP and tempso are inspected 

instead and the first value found is taken; if none of them are set, a host-dependent default is used, 
typically /tmp. 

DIAGNOSTICS 

For each revision, ci prints the RCS file the working file, and the number of both the deposited and the preceding revision. 
T he exit status is zero if and only if all operations were successful. 

IDENTIFICATION 

Author: Walter F. Tichy. 

M anual page revision: 5.17; Release date 16June 1995 
Copyright © 1982,1988,1989 Walter F. Tichy 
C opyright © 1990,1991,1992,1993,1994,1995 Paul Eggert 
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SEE ALSO 

co(l), emacs(l), ident(l), make(l), rcs(l), rcsclean(l), rcsdiff(1), rcsintro(l), rcsmerge(l), nlog(l), setuid(2), rcsfile(5) 
Walter F. Tichy, "RCS—A System forVersion Control,” Software Practice & Experience 15, 7 (July 1985), 637-654. 

GNU, 16 Junel995 

cidentd 

cidentd— identd Server 

SYNOPSIS 

cidentd [-usqvnah] [-f file] [-1 file] [-t seconds] 

DESCRIPTION 

cidentd gives authentication information. 

cidentd is an RFC 1314- and 931-compliant identd daemon. It accepts connections on a port (113 default) and answers 
queries for port owner of a connection, command; 

cidentd normally terminates when the remote command does. The options are as follows: 

-u T urns on the use of the .authiie file in the user's home directory to give the requesting system whatever 

information the user provides. This file is overridden by the - a option and the system file the format is as 
follows: 

mynameis name-to-be-given # give this userid 

hideme # hide user id 

host-ip name-to-be-given # userid for them 

host-ip no-info # hide you to them 

host-ip can bean ip in dot notation or a name. The file is set so that whatever comes last is what they get. 

-s Closes the connection after a single query. 

-q Quits the daemon after 1 connection (default in 1.0b). 

-v Turns on verbose logging to the syslogs. 

-n M akescident act liketheold school identd with nothing special. 

-a Enables the /etc/cident. users file for options, which overrides the user files if -u is specified. The format 

is as follows: 

username name-to-send # send this for username 

username # must send there username 

all name-to-send # send for every query 

all no-info # send nothing every query 

host-ip name-to-send # send to that host 

host-ip no-info # send nothing to them 

host-ip can bean ip in dot notation or a name. The file is set so that whatever comes last is what they get. 

-h D isplays the help list to the screen you might not want to do thisfrom some terminal types. 

-f Sets the file to find the ports and ids of connections. U sethis to specify a file other than /proc/net/tcp. 

-1 Used to specify a file other than /etc/cident. users must be used with the -a option unless you like 

redundancy. 

Sets the time out of a connection in seconds. This does not work in this version to cidentd. 


-t 
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If no arguments are specified, the program just runs as normal, almost like the -n. 
cidemd -t 30 -a sets timer to 30 seconds and tells it to look at .authiie files. 

FILES 

/etc/cidentd.users 
$(HOME)/.authiie 

SEE ALSO 

identd(l) 

BUGS 

N one that I know of. 

Linux/FreeBSD, May 1996 


cksum 

cksum— C hecksum and count the bytes in a file 

SYNOPSIS 

cksum [ — help] [—version] [file...] 

DESCRIPTION 

This manual page documents the G N U version of cksum. cksum computes a cyclic redundancy check (CRC) for each named 
file, or the standard input if none are given or when a file named - is given. It prints the CRC for each file along with the 
number of bytesin thefile, and thefilenameunless no arguments were given. 

cksum is typically used to make sure that files transferred by unreliable means (such asnetnews) have not been corrupted. This 
is accomplished by comparing the cksum output for the received files with thecksum output for the original files. TheCRC 
algorithm is specified by the PO SIX.2 standard. It is not compatible with the BSD or System V sum programs; it is more 
robust. 

Availableoptionsare 

-help Print a usage message and exit with a nonzero status. 

-version Print version information on standard output then exit. 

GNU Text Utilities 


clear 

clear— Clear terminal screen 

SYNOPSIS 

clear 

DESCRIPTION 

clear calls tput(l) with the clear argument. This causes tput to attempt to clear the screen, checking the data in /etc/termcap 
(for the GNU or BSD tput) or in theterminto database (for the ncurses tput) and sending the appropriate sequence to the 
terminal. This command can be redirected to clear the screen of some other terminal. 
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SEE ALSO 

reset(l), stty(l), tput(l) 

AUTHOR 

Rik Faith (faith@cs.unc.edu) 

LinuxO.99,10 October 1993 


cmuwmtopbm 

cmuwmtopbm— Convert aCM U window manager bitmap into a portable bitmap 

SYNOPSIS 

cmuwmtopbm [cmuwmfile] 

DESCRIPTION 

Reads a CM U window manager bitmap as input. Produces a portable bitmap as output. 

SEE ALSO 

pbmtocmuwm(l), pbm(5) 

AUTHOR 

Copyright© 1989 byjef Poskanzer 

15 April 1989 


CO 

co— Check out RCS revisions 

SYNOPSIS 

co [options] file ... 

DESCRIPTION 

co retrieves a revision from each RCS file and stores it into the corresponding working file. 

Pathnames matching an RCS suffix denote RCS files; all others denote working files. N ames are paired as explained in ci(l). 

Revisions of an RCS file can be checked out locked or unlocked. Locking a revision prevents overlapping updates. A revision 
checked out for reading or processing (for example, compiling) need not be locked. A revision checked out for editing and 
later checkin must normally be locked. Checkout with locking fails if the revision to be checked out is currently locked by 
another user. (A lock can be broken with rcs(l).) Checkout with locking also requires the caller to be on the access list of the 
RC S fi le, unless he is the owner of the file or the superuser, or the access list is empty. C heckout without locking is not 
subject to access list restrictions, and is not affected by the presence of locks. 

A revision is selected by options for revision or branch number, checkin dat^time, author, or state. W hen theselection 
options are applied in combination, co retrieves the latest revision that satisfies all of them. If none of theselection options is 
specified, co retrieves the latest revision on the default branch, normally the trunk; see the-b option of rcs(l). A revision or 
branch number can be attached to any of the options -f, -i, -i, -m, -p, -q, -r, or -u. The options -d (date), -s (state), and -w 
(author) retrieve from a single branch, the selected branch (which is specified by -f or -u), or the default branch. 

A co command applied to an RCS file with no revisions creates a zero-length working file, co always performs keyword 
substitution. 
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OPTIONS 

- r [ r e v ] Retria/es the latest revision who® number is less than or equal tore*. If re* indicates a branch 

rather than a revision, the latest revision on that branch is retrieved. If rev is omitted, the latest 
revision on the default branch is retrieved; seethe-b option of rcs(l). If rev is $, co determines the 
revision number from keyword values in the working file. Otherwise a revision is composed of one 
or more numeric or symbolic fields separated by periods. If rev begins with a period, then the 
default branch (normally the trunk) is prepended to it. If rev is a branch number followed by a 
period, then the latest revision on that branch is used. The numeric equivalent of a symbolic field is 
specified with the-n option of the commands c±(l) and rcs(l). 

-l [ r e v ] Sameas-r, except that it also locksthe retrieved revision for the caller. 

-u [ r e v ] Sameas-r, except that it unlocks the retrieved revision if it was locked by the caller. Ifrev is 

omitted, -u retrievesthe revision locked by thecaller, if there is one; otherwise it retrieves the latest 
revision on the default branch. 

-t [rev ] Forces the overwriting of the working file; useful in connection with -q. (See also "FileM odes," 

later in this manual page.) 

-kkv Generate keyword strings using the default form, forexample, $Revision: 5.13 $ for the Revision 

keyword. A locker's name is inserted in the value of the Header, id, and Locker keyword strings only 
as a file is being locked, that is, by ci -landco -1. This isthe default. 

-kkvi Like -kkv, except that a locker's name is always inserted if the given revision is currently locked. 

-kk Generate only keyword namesin keyword strings; omit their values. (See'Teyword Substitution," 

later in this manual page.) Forexample, for the Revision keyword, generate the stri ng $Revision$ 
instead of $Revision: 5.13 $. This option is useful to ignore differences due to keyword substitu¬ 
tion when comparing different revisions of a file. Log messages are inserted after $Log$ keywords 
even if -kk is specified, si nee this tends to be more useful when merging changes. 

-ko Generate the old keyword string, present in the working file just before it was checked in. For 

example, for the Revision keyword, generate the string $Revision: 1.1 $ instead of $Revision: 5.13 
$ if that is how the string appeared when the file was checked in. This can be useful for file formats 
that cannot tolerate any changes to substrings that happen to take the form of keyword strings. 

-kb Generate a binary image of the old keyword string. This acts like -ko, except it performs all 

working file input and output in binary mode. This makes little difference on POSIX and U NIX 
hosts, but on DOS-like hosts one should use res -i -kb to initialize an RCS file normally refuses 
to merge files when -kb isin effect. 

-kv Generate only keyword values for keyword strings. Forexample for the Revision keyword, generate 

thestring 5.13 instead of$Revision: 5.13 $. T his can help generate files in programming languages 
where it is hard to strip keyword delimiters like $Revision : $ from a string. FI owever, further 
keyword substitution cannot be performed once the keyword names are removed, so thisoption 
should be used with care. Becauseofthisdangerof losing keywords, thisoption cannot be 
combined with -1, and the owner write permission of the working file is turned off; to edit the file 
later, check it out again without -kv. 

-p [ r e v ] Prints the retrieved revision on the standard output rather than storing it in the working file This 

option is useful when co is part of a pipe 
-q [rev] Quiet mode; diagnostics are not printed. 

-1 [r ev ] Interactive mode; the user is prompted and questioned a/en if the standard input is not a terminal, 

-dd a t e Retria/es the latest revision on the selected branch whose checkin date/time is less than or equal to 

date. Thedateand time can be given in free format. The time zone lt stands for local time; other 
common time zone names are understood. Forexample, the foil owing dates are equivalent if local 
time is January 11,1990, 8 p.m. Pacific Standard Time, eight hours west of Coordinated Universal 
Time(UTC): 



8:00 PM It 

4:00 AM, Jan. 12,1990 


Default isUTC 
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1990-01-12 04:00:00+00 
1990-01-11 20:00:00-08 
1990/01/12 04:00:00 
Thujan 11 20:00:00 1990 LT 
Thujan 11 20:00:00 PST 1990 
Fri Jan 12 04:00:00 GMT 1990 
Thu, 11J an 1990 20:00:00 -0800 
12-January-1990, 04:00 WET 


ISO 8601 (UTC) 

ISO 8601 (local time) 

T raditional RCS format 
Output of ctime(3) +LT 
Output of date(l) 

Internet RFC 822 


M ost fields in the date and time can be defaulted. T he default time zone is normally UT C, but this can be overridden by the 
-z option. Theother defaults are determined in theorder year, month, day, hour, minute, and second (most to least 
significant). At least one of these fields must be provided. For omitted fields that are of higher significance than the highest 
provided field, the time zone's current values are assumed. For all other omitted fields, the lowest possible values are 
assumed. For example without-z, thedate 20,10:30 defaults to 10:30:00 UTC of the 20th of theUTC time zone's current 
month and year. The dat^ti me must be quoted if it contains spaces. 


-m [rev] Sets the modification time on the new working file to be the date of the retrieved revision. Use this 

option with care; it can confuse make(l). 

-sstate Retrieves the latest revision on the selected branch whose state is set to state. 

-t Preserves the modification time on the RC S file even if the RC S fi le changes because a lock is 

added or removed. This option can suppress extensive recompilation caused by amake(l) depen¬ 
dency of some other copy of the working file on the RCS file. Usethisoption with care; it can 
suppress recompilation even when it is needed, in other words, when the change of lock would 
mean achangeto keyword strings in the other working file. 

-w[i ogi n ] Retrieves the latest revision on the selected branch that was checked in by the user with login name 

i og i n . If the argument login is omitted, the caller's login is assumed. 

-jj oi ni i st Generates a new revision which is the join of the revisions on j oi ni i st . This option is largely made 

obsolete by rcsmerge(l), but is retained for backwards compatibility. 

Thej oi ni i st is a comma-separated list of pairs of the form re* 2: r ev3 , where rev2 and re»3 are 
(symbolic or numeric) revision numbers. For the initial such pair, r evl denotes the revision selected 
by the options-f, -w. For all other pairs, r ev l denotes the revision generated by the previous pair. 
(Thus, the output of one join becomes the input to the next.) 

For each pair, co joins revisions r ev l and re* 3 with respect to re* 2 . This means that all changes that 
transform re* 2 into rev l are applied to a copy of re v3. This is particularly useful if r ev l and r ev 3 
are the ends of two branches that haver ev 2 as a common ancestor. Ifrevi<rev2<rev3 on the same 
branch, joining generates a new revision which is like r ev 3 , but with all changes that lead from re vi 
to rev 2 undone If changes from rev 2 to rev l overlap with changes from re *2 to r ev3, co reports 
overlaps as described in merge(l). 

Fortheinitial pair, rev 2 can be omitted. T he default isthecommon ancestor. If any of the 
arguments indicate branches, the latest revisionson those branches are assumed. The options -i 
and -u lock or unlock rev i . 

-v PrintsRCS'sversion number. 


-vn Emulates RCS version n, where n can be 3, 4, or 5. This can be useful when interchanging RCS 

files with others who are running older versions of RCS. To see which version of RCS your 
correspondents are running, have them invoke res -v; this works with newer versions of RCS. If it 
doesn'twork, have them invokeriog on an RCSfile; if none of thefirst few linesof output contain 
the string branch:, it is version 3; if the dates' years have just two digits, it is version 4; otherwise, it 
is version 5. An RCS file generated while emulating version 3 loses its default branch. An RCS 
revision generated while emulating version 4 or earlier has a timestamp that is off by up to 13 
hours. A revision extracted while emulating version 4 or earlier contains abbreviated dates of the 
form yy/mm/dd and can also contain different whitespaceand line prefixes in the substitution for 
$Log$. 
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Uses suffixes to characterize RCS files. See ci(l) for details 

Specifies the date output format in keyword substitution, and specifiesthe default time zonefor 
date in the -ddat e option. The zone should be empty, a numeric UTC offset, or the special string 
lt for local time The default is an empty zone, which uses the traditional RCS format of UTC 
without any time zone indication and with slashes separating the parts of the date otherwise times 
are output in ISO 8601 format with time zone indication. For example, if local timeisjanuary 11, 
1990, 8 p.m. Pacific Standard Time, eight hours west of UTC, then the time is output as follows: 

Option Time Output 

-z 1990/01/12 04:00:00 (default) 

-zLT 1990-01-11 20:00:00-08 

-z+05:30 1990-01-12 09:30:00+05:30 

The-z option does not affect dates stored in RCS files, which are always UTC. 

KEYWORD SUBSTITUTION 

Stringsof theform $ keyword $and$ keyword : ... $ embedded in the text are replaced with strings of theform $ keyword 
: value $, where keyword and vai ue are pairs in the foil owing list. Keywords can be embedded in literal strings or comments 
to identify a revision. 

Initially, the user enters strings of theform $key wo r d $. On checkout, co replaces these strings with strings of theform 
$k e y wo r d : vai ue$. If a revision containing strings of the latter form is checked back in, thevai ue fields will be replaced 
during the next checkout. T hus, the keyword values are automatically updated on checkout. This automatic substitution can 
be modified by the -k options 

Keywords and their corresponding values: 

$a u t h o r $ Thelogin name of the user who checked in the revision. 

$Date$ The date and time the revision was checked in. With -zz one, a numeric time zone offset is 

appended; otherwise the date is UTC. 

$h e a d e r $ A standard header containingthefull pathname of the RCS file the revision number, the date and 

time, the author, the state, and the locker (if locked). With -zz one, a numeric time zone offset is 
appended to the date; otherwise, thedateisUTC. 

$i d$ SameassHeader $, except that the RC S filename is without a path. 

$l o c k e r $ The login name of the user who locked the revision (empty if not locked). 

$Log$ The log message supplied during checkin, preceded by a header containing the RCS filename the 

revision number, the author, and the date and time W ith -zzone a numeric time zone offset is 
appended; otherwise thedateisUTC. Existing log messages are not replaced. Instead, the new log 
message is inserted after $l o g: ... $. This is useful for accumulating a complete change log in a 
source file. 

Each inserted line is prefixed by the string that prefixes the $ug$ line. For example, if the $Log $ line is// $Log: tan.cc $, 
RCS prefixes each line of the log with //. This is useful for languages with comments that go to the end of the line The 
convention for other languages is to use a * prefix inside a multiline comment. For example, the initial log comment of aC 
program conventionally is of thefollowingform: 

/* 

* $Log$ 

*/ 

For backwards compatibility with older versions of RCS, if the log prefix is/* or (* surrounded by optional whitespace, 
inserted log lines contain aspaceinstead of / or (; however, this usage is obsolescent and should not be relied on. 

The symbolic name used to check out the revision, if any. For example co -r Joe generates $Name : 
joe $. Plain co generates just $Name : $. 


-xsuf f i xes 
-zzone 


$Name$ 
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$Rcsf i i e $ The name of the RC S file without a path. 

$r e v i si o n $ The revision number assigned to the revision. 

$s o u r c e $ Thefull pathname of the RC S file. 

$s t a t e $ The state assigned to the revision with the-s option of rcs(l) or ci(l). 

Thefollowing characters in keyword values are represented by escape sequences to keep keyword strings well-formed. 

Character Escape Sequence 


tab 

vt 

newline 

\n 

space 

\040 

$ 

\044 

\ 

\\ 


FILE MODES 

Theworking file inherits the read and execute permissions from the RC S file. In addition, theowner write permission is 
turned on, unless -kv is set or the file is checked out unlocked and locking is set to strict; see rcs(l). 

If a file with the name of the working file exists already and has write permission, co aborts the checkout, asking beforehand 
if possible. I f the existi ng working file is not writable or -f isgiven, the working file is deleted without asking. 

FILES 

co accesses files much asci(l) does, except that it does not need to read the working file unless a revision number of $ is 
specified. 

ENVIRONMENT 

rcsinit Options prepended to the argument list, separated by spaces. Seeci(l) for details. 

DIAGNOSTICS 

T he RCS pathname theworking pathname, and the revision number retrie/ed are written to the diagnostic output. The exit 
statusiszero if and only if all operations were successful. 

IDENTIFICATION 

Author: Walter F. Tichy. 

M anual Page Revision: 5.13; Release D ate: 1995/06/01. 

Copyright © 1982,1988,1989 Walter F. Tichy. 

Copyright© 1990,1991,1992,1993,1994,1995 Paul Eggert. 

SEE ALSO 

rcsintro(l), ci( 1), ctime(3), date(l), ident(l), make(l), rcs(l), rcsclean(l), rcsdiff(l), rc-smerge(l), rlog(l), rcsfile(5) 
Walter F. Tichy, "RCS—A System forVersion Control," Software Practice & Experience 15,7 (July 1985), 637-654. 

LIMITS 

Links to the RCS and working files are not preserved. 

There is no way to selectively suppress the expansion of keywords, except by writing them differently. In nroff and troff, 
thisisdoneby embeddingthenull-character \& into thekeyword. 


GNU,lJunel995 
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col 

coi— Filter reverse line feeds from input 

SYNOPSIS 

col [ -bfx] [-1 num] 

DESCRIPTION 

coi filters out reverse (and half-reverse) linefeeds so the output is in the correct order with only forward and half-forward 
linefeeds, and replaces whitespace characters with tabs where possible. This can be useful in processing the output of 
nroft(l) and tbi(l). coi reads from standard input and writes to standard output. 

The options are as follows: 

-b Do not output any backspaces, printing only the last character written to each column position. 

-f Forward half-line feeds are permitted (fine mode). N ormally characters printed on a half-line boundary 

are printed on the following line. 

-x Output multi pie spaces instead of tabs. 

-lnum Buffer at least num lines in memory. By default, 128 lines are buffered. 

The control sequences for carriage motion that coi understands and their decimal values are listed in the following table 



Control Sequence Deamal Value 


Esc+7 
Esc+8 
Esc-T9 
Backspace 
Carriage return 
N ewline 
Shift in 
Shift out 
Space 
T ab 

Vertical tab 


Reverse linefeed (escapethen 7) 

Half-reverse linefeed (escape then 8) 

H alf-forward linefeed (escapethen 9) 

M oves back one column (8); ignored in the first column 
(13) 

Forward linefeed (10); also does carriage return 
Shift to normal character set (15) 

Shift to alternate character set (14) 

M oves forward one column (32) 

M oves forward to next tab stop (9) 

Reverse linefeed (11) 


All unrecognized control characters and escape sequences are discarded. 

coi keepstrack of the character set as characters are read and makes sure the character set is correct when they are output. 
If the input attempts to back up to the last flushed line, coi will display a warning message. 


SEE ALSO 

expand(l), nnoff(l), tbl(l) 


HISTORY 

A coi command appeared in version 6 AT&T UNIX. 


17 ]unel991 
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colcrt 

coicr-t — Filter nroff output for CRT previewing 

SYNOPSIS 

colcrt [-] [-2] [file ... ] 

DESCRIPTION 

colcrt provides virtual half-line and reverse-line feed sequences for terminals without such capability, and on which 
overstriking is destructive. H alf-line characters and underlining (changed to dashing-) are placed on new lines in between 
the normal output lines. 

Available options: 

Suppress all underlining. Thisoption isespecially useful for previewing all boxed tables from tbi(l). 

-2 Causes all half-lines to be printed, effectively double spacing the output. Normally, a minimal space 

output format is used which will suppress empty lines. The program never suppresses two consecutive 
empty lines, howa/er. The -2 option is useful for sending output to the I ine printer when theoutput 
contains superscripts and subscripts that would otherwise be invisible. 

EXAMPLES 

A typical use of colcrt would be 

tbl exum2.n | nroff -ms | colcrt - | more 

SEE ALSO 

nroff(l), troff(l), col(l), more(l), ul(l) 

BUGS 

Should fold underlines onto blanks even with the - option so that a true underline character would show. 

Can't back up morethan 102 lines. 

General overstriking is lost; asa special case ; overstruck with " or underline becomes+. Linesaretrimmed to 132 
characters. 

Some provision should be made for processing superscripts and subscri pts in documents that are already double-spaced. 

HISTORY 

The colcrt command appeared in BSD 3.0. 

BSD 3, 30 Junel993 


colrm 

coirm— Remove columnsfrom afile 

SYNOPSIS 

colrm [startcol [endcol ]] 

DESCRIPTION 

coirm removes selected columnsfrom afile. Input is taken from standard input. Output is sent to standard output. 

If called with one parameter, the columns of each line will be removed starting with the specified column. If called with two 
parameters, the columnsfrom the first column to the last column will be removed. 

Column numbering starts with column 1. 
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SEE ALSO 

awk(l), column(l), expand(l), paste(l) 

HISTORY 

The coi™ command appeared in BSD 3.0. 

BSD 3,14 March 1991 


column 

column— C olumnate lists 

SYNOPSIS 

column [-tx] [-ccolumns] [-ss ep ] [...file] 

DESCRIPTION 

T he column utility formats its input into multiplecolumns Rows are filled before columns. Input istaken from fi le operands, 
or, by default, from the standard input. Empty lines are ignored. 

The options are as follows: 

-c Output isformatted for a display columnswide. 

-s Specify a set of characters to be used to delimit columns for the -t option. 

-t Determine the number of columns the input contains and create a table. Columns are delimited with 

whitespace, by default, or with the characters supplied using the -s option. Useful for pretty-printing 
displays. 

-x Fill columns beforefilling rows. 

C olumn exits 0 on success, >0 if an error occurred. 

ENVIRONMENT 

The environment variable columns isused to determine the size of the screen if no other information is available. 

EXAMPLES 

(printf "PERM LINKS OWNER SIZE MONTH DAY HH:MM/YEAR NAME"; Is -1 j sed Id) j column -t 

SEE ALSO 

colrm(l), ls( 1), paste(l), sort(l) 

HISTORY 

The column command appeared in BSD 4.3 Reno. 

6 ]unel993 


comm 

comm— Compare two sorted filsline by line 

SYNOPSIS 

comm [-123] [ — help] [—version] filel f i I e 2 



convdate 



DESCRIPTION 

This manual page documents the GN U version of comm, comm prints lines that are common, and lines that are unique to two 
input files. Thetwo files must be sorted before comm can be used. The filename- means the standard input. 

With no options, comm produces three column output. Column one contains lines unique to f i i ei , column two contains 
lines unique to f i i e 2 , and column three contains lines common to both files. 

OPTIONS 

T he options-i, - 2 , and -3 suppress printing of the corresponding columns. 

-help Print a usage message and exit with a nonzero status. 

-version Print version information on standard output then exit. 

GNU Text Utilities 


convdate 

convdate— C onvert time/datestrings and numbers 

SYNOPSIS 

convdate [ -c ][-n ][ -s ] a r g ... 

DESCRIPTION 

convdate translates the date/time strings specified asargumentson its command line, outputting the results oneto a line. 

If the -s flag is used, then each argument is taken as a date stri ng to be parsed by parse-date(3) and is output as a string 
formatted by ctime(3). This is the default. 

If the -n flag is used, then each argument is converted the same way but is output as a timet; seetime(2). 

If the -c flag is used, then each argument is taken to be a timet and is output in ctime format. 

H ere'san example 

% convdate 1 feb 10 10am 1 
Sun Feb 10 10:00:00 1991 

% convdate 12pm 5/4/90 
Fri Dec 13 00:00:00 1991 
Fri May 4 00:00:00 1990 

% convdate -n 1 feb 10 10am 1 '12pm 5/4/90' 

666198000 

641880000 

% convdate -c 666198000 
Sun Feb 10 10:00:00 1991 

HISTORY 

Written by Rich $alz (rsaiz@uunet.uu.net). 

SEE ALSO 

parsedate(3) 
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cp 

cp— Copy files 

SYNOPSIS 

cp [options] source dest 
cp [options] source... directory 

Options: 

[-abdfilprsuvxPR] [-S backup-suffix] [-V fnumbered,existing,simpleg] [—backup] 
[—no-dereference] [—force] [—interactive] [-one-file-system] [—preserve] 

[— recursive] [— update] [—verbose] [ —suffix=backup-suffix] 

[ — version-control=fnumbered,existing,simpleg] [ — archive] [ — parents] [—link] 
[-symbolic-link] [—help] [—version] 


DESCRIPTION 

This manual page documents the GN U version of cp. If the last argument names an existing directory, cp copies each other 
given file into a file with the same name in that directory. Otherwise if only two files are given, it copies the first onto the 
second. It is an error if the last argument is not a directory and more than two files are given. By default, it does not copy 
di recto ri es. 


OPTIONS 

-a, —archive 

-b, —backup 

-d, —no-dereference 

-f, —force 
-i, —interactive 
-1, -link 
-P, —parents 


-p, —preserve 
-r 

-s, —symbolic-link 


-u, —update 

-v, —verbose 

-x, -one-file-system 

-R, —recursive 

— help 

— version 

-S, —suffix backup-suffix 


Preserve as much as possible of the structure and attributes of theoriginal filesin the copy. 
The same as -dpR. 

M ake backups of files that are about to be overwritten or removed. 

Copy symbolic links as symbolic I inks rather than copying the files that they point to, and 
preserve hard link relationships between source filesin thecopies 
Remove existing destination files. 

Prompt whether to overwrite existing regular destination files. 

M ake hard links instead of copiesof nondirectories. 

Form the name of each destination file by appending to the target directory a si ash and the 
specified name of the source file. The last argument given to cp must be the name of an 
existing directory. For example thecommand cp -parents a/b/c existing_dir copies the 
file a/b/c to existing_dir/a/b/c, creating any missing intermediate directories. 

Preserve the original files' owner, group, permissions, and timestamps. 

C opy directories recursively, copying all nondirectories as if they were regular files. 

M ake symbolic links instead of copiesof nondirectories. All source filenames must be 
absolute (starting with /) unless the destination files are in the current directory. This 
option produces an error message on systemsthat do not support symbolic links. 

Do not copy a nondirectory that has an existing destination with the same or newer 
modification time 

Print the name of each file before copying it. 

Skip subdirectories that are on different filesystems from the one that the copy started on. 

C opy directories recursively. 

Print a usage message on standard output and exit successfully. 

Print version information on standard output then exit successfully. 

The suffix used for making simple backup files can beset with thesiMPLE_BACKUP_suFFix 
environment variable, which can be overridden by this option. If neither of those is given, 
the default is-, as it is in emacs. 
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-v, -version-control T he type of backups made can be set with the version_control environment variable, which 

{numbered, existing, simple} can be overridden by this option. If version_control is not set and this option is not given, 

the default backup type is existing. T he value of the version_control environment variable 
and theargumentto thisoption are like the G N U emacs version- control variable; they 
also recognize synonyms that are more descriptive. The valid values are (unique abbrevia¬ 
tions are accepted) the following: 

t or numbered Always make numbered backups 

mi or existing Makenumbered backups of files that already havethem, 

si mple backups of the others 
never or simple Always make simple backups 

cccp, cpp 

cccp, cpp—TheGNU C-compatiblecompiler preprocessor 

SYNOPSIS 

cccp [-$ ] [ -A predi cate [(value ) ] ] [ -C ] [-D name [ = def i ni t i on ] ] 

[-dD][-dM][ -I \ directory ][-H ][-I- ][-imacros file ][- 

include file ][-idirafter dir ][-iprefix prefix ][-iwithprefix dir ] 

[ -lang-c][-lang-c++][-lang-objc ][-lang-objc++ ][-lint ][- 
M[-MG ]] [ -MM[-MG ]] [ -MD file ][-MMD file ][-nostdinc ] 

[ -nostdinc++][-P][-pedantic ][-pedantic-errors ][-traditional ] 

[ -trigraphs ][-U name ][-undef ][-Wtrigraphs ][-Wcomment ] 

[ -Wall ][-Wtraditional ] 

[infile ][ outfile |- ] 

DESCRIPTION 

TheC preprocessor is a macro processor that is used automatically by the C compiler to transform your program before 
actual compilation. It is called a macro processor because it allows you to define macros, which are brief abbreviations for 
longer constructs. 

TheC preprocessor provides four separate facilities that you can use as you see fit: 

■ Inclusion of header files. These are files of declarations that can be substituted into your program. 

■ M aero expansion. You can define macros, which are abbreviations for arbitrary fragments of C code, and then theC 
preprocessor will replace the macros with their defi nitions throughout the program. 

■ Conditional compilation. Using special preprocessing directives, you can include or exclude parts of the program 
according to various conditions. 

■ Line control. If you use a program to combine or rearrange sourcefiles into an intermediate file which is then compiled, 
you can use line control to inform the compiler of where each source lineoriginally camefrom. 

C preprocessors vary in some details. For a full explanation of the GNU C preprocessor, see the into file cpp. into, or the 
manual TheC Preprocesor . Both of these are built from the same documentation source file, cpp.texinto. TheGN U C 
preprocessor provides a superset of the features of AN SI Standard C. 

ANSI Standard C requires the rq ection of many harmless constructs commonly used by today's C programs. Such 
incompatibility would be inconvenient for users, sotheGNU C preprocessor is configured to accept these constructs by 
default. Strictly speaking, to get AN SI Standard C, you must use the options-trigraphs, -undef, and -pedantic, but in 
practicethe consequences of having strict AN SI Standard C make it undesirable to do this. 

When you use theC preprocessor, you will usually not have to invoke it explicitly: theC compiler will do so automatically. 

H owever, the preprocessor issometimes useful individually. 

When you call the preprocessor individually, either name (cpp or cccp) will do; they are completely synonymous. 
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TheC preprocessor expects two filenames as arguments, infile and outfiie. The preprocessor reads inf iie together with 
any other files it specifies with #inciude. All the output generated by the combined input files is written in outfiie. Either 
infiie or outfiie may be-, which asinfiie means to read from standard input and as outfiie means to write to standard 
output. Also, if outfiie or both filenames are omitted, the standard output and standard input are used for the omitted 
filenames. 


OPTIONS 


H ere is a table of command options accepted by the C preprocessor. These options can also be given when compiling a C 
program; the/ are passed along automatically to the preprocessor when it is invoked by the compiler. 


-p 

-c 

-traditional 

-trigraphs 


-pedantic 

-pedantic-errors 

-Wtrigraphs 

-Wcomnent 

-Wcomments 

-Wall 

-Wtraditional 
-I directory 


-nostdinc 

-nostdinc++ 

-D name 

-D n a me =d e f i ni t i on 


Inhibit generation of# lines with line-number information in the output from the preprocessor. 
This might be useful when running the preprocessor on something that is not C code and will be 
sent to a program which might be confused by the# lines. 

Do not discard comments: pass them through to the output file. Commentsappearing in 
arguments of a macro call will be copied to the output before the expan si on of the macro call. 

Try to imitate the behavior of old-fashioned C, as opposed to AN SI C. 

Process AN SI standard trigraph sequences. These are three-character sequences, all starting with ??, 
that are defined by AN SI C to stand for single characters. For example ??/ stands for \, so ??/n is a 
character constant for a newline. Strictly speaking, theGN U C preprocessor does not support all 
programs in AN SI Standard C unless -trigraphs is used, but if you ever notice the difference it 
will be with relief. You don't want to know any more about trigraphs. 

Issue warnings required by the AN SI C standard in certain cases such as when text other than a 
comment follows #else Or#endif. 

Like -pedantic, except that errors are produced rather than warnings. 

W arn if any tri graphs are encountered (assumi ng they are enabled). 

Warn whenever a comment-start sequence /* appears in a comment. (Both forms have the 
same effect.) 

Requests both -Wtrigraphs and -Wcomment (but not -Wtraditional). 

Warn about certain constructs that behave differently in traditional andANSI C. 

Add the directory di rectory to the end of the list of directories to be searched for header files. This 
can be used to override a system header file, substituting your own version, si nee these directories 
are searched before the system header file directories. If you use more than one-i option, the 
directories are scanned in left-to-right order; thestandard system directories come after. 

Any directories specified with -i options before the-i- option are searched only for the case of 
#inciude " file "; they are not searched for #inciude < file >. 

If additional directories are specified with -i options after the -i-, these directories are searched for 
all #inciude directives. 

In addition, the-i- option inhibits the use of the current directory as the first search directory for 
#inciude " file ". T herefore the current di rectory is searched only if it is requested explicitly with 
-i followed by a period (.). Specifying both -i- and -i. allows you to control precisely which 
directories are searched before the current one and which are searched after. 

Do not search thestandard system directories for header files. Only the directories you have 
specified with -i options (and the current directory, if appropriate) are searched. 

Do not search for header files in theC-H-specific standard directories, but do still search the other 
standard directories. (Thisoption isused when building iibg++.) 

Predefine name asa macro, with definition i. 

Predefine name as a macro, with definition def i ni t i on. There are no restrictions on the contents of 
definition, but if you are invoking the preprocessor from a shell or shell-likeprogram, you may 
need to use the shell's quoting syntax to protect characters such as spaces that have a meaning in 
the shell syntax. If you use more than one-D for the same name, the rightmost definition takes 
effect. 
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-U name 

-undef 

-A name (value) 


-dM 


-dD 


-M[-MG] 


-MM[-MG] 


-MDf i I e 


-MMDf i I e 
-H 

-imacros file 


-include file 
-idirafter di r 


-iprefix prefix 
-iwithprefix di r 

-lang-c 

-lang-c++ 

-lang-objc 

-lang-objc++ 

-lint 


Do not predefine name. If both -u and -d are specified for one name, the-u beats the -d and the 
name is not predefined. 

Do not predefine any nonstandard macros. 

Assert (in the same way asthe#assert directive) the predicate name with tokeniist value. 
Remember to escape or quote the parentheses on shell command lines. You can use -a- to disable 
all predefined assertions; it also undefines all predefined macros. 

Instead of outputting the result of preprocessing, output a list of #define directives for all the 

macros defined during the execution of the preprocessor, including predefined macros. This gives 

you away of finding out what is predefined in your version of the preprocessor; assuming you have 

no filefoo.h, thecommand 

touch foo.h; cpp -dM foo.h 

will show thevaluesof any predefined macros. 

Like -dM except in two respects: it does not include the predefined macros, and it outputs both the 
#detine directives and the result of preprocessing. Both kinds of output go to the standard output 
file. 

Instead of outputting the result of preprocessing, output a rule suitable for make describing the 
dependencies of the main source file The preprocessor outputs one make rule containing the 
object fi lenamefor that source file, a colon, and the names of all the included files. If there are 
many included files then the rule issplit into several lines using \\ (newline). 

-mg says to treat missing header files as generated files and assume they live in the same directory as 
the source file. It must be specified in addition to -m. 

This feature is used in automatic updating of makefiles. 

Like -m but mention only thefiles included with #inciude * me System header files included 
with #inciude < file > are omitted. 

Like -m but the dependency information is written to tile. This is in addition to compiling the file 
as specified, -md does not inhibit ordinary compilation theway -m does. 

When invoking gcc, do not specify thef i i e argument, gcc will create filenames made by replacing 
.c with .d at the end of the input filenames. 

In M ach, you can use the utility md to merge multi pie files into a single dependency file suitable for 
using with the make command. 

Like -m except mention only user header files, not system header files. 

Print the name of each header file used, in addition to other normal activities. 

Process file as input, discarding the resulting output, before processing the regular input file. 
Because the output generated from file is discarded, the only effect of -imacros file is to make the 
macros defined in file available for use in the main input. The preprocessor evaluates any -d and -u 
options on thecommand line before processing-imacrosfile. 

Process f i i e as input, and include all the resulting output, before processing the regular input file. 
Add the di rectory di r to the second include path. The directories on the second include path are 
searched when a header file is not found in any of the directories in themain include path (theone 
that -i adds to). 

Specify p ref i * as the prefix for subsequent -iwithprefix options 

Add a directory to the second include path. The directory's name is made by concatenating prefix 
and dir, where prefix was specified previously with -iprefix. 

Specify the source language. -iang-c++ makes the preprocessor handle C++comment syntax, 
and includes extra default include directories for C++, and -lang-objc enables the 0 bjective C 
#import directive, -iang-c explicitly turns off both of these extensions and -iang-objc++ enables 
both. T hese options are generated by the compi ler driver gcc, but not passed from the gcc 
command line. 

Look for commands to the program checker lint embedded in comments, and emit them preceded 
by #pragma lint. For example the comment /* notreached */ becomes #pragma lint notreached. 
This option is avail able only when you call cpp directly; gcc will not pass it from its command line. 
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-$ Forbid the use of $ in identifiers. This is required for AN SI conformance, gcc automatically 

supplies this option to the preprocessor if you specify -ansi, but gcc doesn't recognize the-$ 
option itself; to use it without the other effects of -ansi, you must call the preprocessor directly. 

SEE ALSO 

cpp entry in into; TheC Preprocessor, Richard M . Stallman. 

gcc(l); gcc entry in into; Usngand Porting GNU CC (for version 2.0), Richard M . Stallman. 

COPYING 

Copyright © 1991,1992,1993 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim 
copies of this manual provided the copyright notice and this permission notice are preserved on all copies. 

Permission isgranted to copy and distribute modified versionsof thismanual under the conditions for verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 

Permission isgranted to copy and distribute translations of thismanual into another language, under the above conditions 
for modified versions, except that this permission notice may be included in translations approved by the Free Software 
Foundation instead of in the original English. 

GNU Tools 30 April 1993 
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crontab— M ani pulate per-user crontabs (D illon'sCron) 


SYNOPSIS 

crontab file [ -u user] 
crontab - [-u user ] 
crontab -1 [user ] 
crontab -e [user ] 
crontab -d [user ] 
crontab -c di r 


Replace crontab from file 
Replace crontab from stdin 
List crontab for user 
Edit crontab for user 
D elete crontab for user 
Specify crontab directory 


DESCRIPTION 

crontab manipulates the crontab for a particular user. 0 nly the superuser may specify a different user and/or crontab 
directory. Generally, the -e option is used to edit your crontab. crontab will use /usr/bin/vi or the editor specified by your 
VISUAL environment variableto edit the crontab. 


Unlike other crond/crontabs, this crontab does not try to do everything under the sun. Frankly, a shell script is much more 
able to manipulate the environment than cron, and I see no particular reason to use the user's shell (from his password entry) 
to run cron commands when this requires special casing of nonuser crontabs, such as those for UUCP. W hen a crontab 
command isrun, thiscrontab runsitwith /bin/sh and setsup only three environment variables: user, home, and shell. 

crond automatically detects changes in the time. Ra/erse-indexed time changes less then an hour old will N OT rerun crontab 
commands already issued in the recovered period. Forward-indexed changes less then an hour into the future will issue 
missed commands exactly once. Changes greater then an hour into the past or future cause crond to resynchronize and not 
issue missed commands. N o attempt will be made to issue commands lost due to a reboot, and commands are not reissued if 
the previously issued command is still running. For example if you have a crontab command sleep 1 0 that you wish to run 
once a minute, cron will only be able to issue the command once every two minutes. If you do not I ike this feature, you can 
run your commands in the background with an &. 
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Thecrontab format is roughly similar to that used by vixiecron, but without complex features. Individual fields may contain 
a time, a time range, a time range with a skip factor, a symbolic range for the day of week and month in year, and additional 
subranges delimited with commas. Blank lines in thecrontab or lines that begin with a hash (#) are ignored. If you specify 
both a day in the month and a day of week, the result is effectively oRd; thecrontab entry will be run on the specified day of 
week and on the specified day in the month. 

# MIN HOUR DAY MONTH DAYOFWEEK COMMAND 

# at 6:10 a.m. every day 
10 6 ***date 

# every two hours at the top of the hour 
0 *12 ***date 

# every two hours from 11p.m. to 7a.m., and at 8a.m. 

0 23-7/2,8 ***date 

# at 11:00 a.m. on the 4th and on every mon, tue, wed 
0 11 4 * mon-wed date 

# 4:00 a.m. on january 1st 
0 4 1 jan *date 

# once an hour, all output appended to log file 
0 4 1 jan *date»/var/log/messages 2>&1 

Thecommand portion of thelineisrun with /btn/sh -c <command>, and may therefore contain any valid Bourneshell 
command. A common practice is to run your command with exec to keep the process table uncluttered. It is also common to 
redirect output to a log file. If you do not, and thecommand generates output on stdout or stderr, the result will be mailed 
to the user in question. If you use this mechanism for special users, such asUUCP, you may want to create an alias for the 
user to direct the mail to someone else, such as root or postmaster. 

Internally, this cron uses a quick indexing system to reduce CPU overhead when looking for commands to execute. Several 
hundred crontabswith several thousand entries can be handled without using noticeable CPU resources. 

BUGS 

Ought to be able to have several crontab files for any given user, as an organizational tool. 

AUTHOR 

M atthew D i I Ion (dillon@apollo.west.oic.com) 

1 May 1994 
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csplit— Split a file into sections determined by context lines 

SYNOPSIS 

csplit [-sqkz] [-f prefix] [-b suffix] [-n digits] [—prefix=prefix] 

[-suffix-format=suffix] [ —digits=digits] [—quiet] [ — silent] 

[-keep-files] [-elide-empty-files] [-help] [ — version] 
file pattern... 

DESCRIPTION 

This manual page documents the GN U version of csplit. csplit creates zero or more output files containing sections of the 
given input file, or the standard input if the name - is given. By default, csplit prints the number of bytes written to each 
output file after it has been created. 
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The contents of the output files are determined by the pattern arguments. An error occurs if a pattern argument refers to a 
nonexistent line of the input file, such as if no remaining line matches a given regular expression. After all the given patterns 
have been matched, any remaining output is copied into one last output file. The types of pattern arguments are 


line 


/regexp/[off set] 


%regexp%[offset] 
{repeat-count} 


Create an output file containing the current lineup to (but not including) line line (a positive 
integer) of the input file. If followed by a repeat count, also create an output file containing the 
next line lines of the input file once for each repeat. 

Create an output file containing the current lineup to (but not including) the next line of the 
input file that contains a match for regexp. The optional offset is a + or - followed by a positive 
integer. If it is given, the input up to the matching line plus or minus offset is put into the output 
file, and the line after that begins the next section of input. 

Likethe previous type except that it does not create an output file, so that section oftheinput file 
is effectively ignored. 

Repeat the previous pattern repeat-count (a positive integer) additional times. An asterisk may be 
given in place of the (integer) repeat count, in which case the preceding pattern is repeated as many 
times as necessary until the input is exhausted. 


The output filenames consist of a prefix followed by a suffix. By default, the suffix is merely an ascending linear sequence of 
two-digit decimal numbers starting with 00 and ranging up to 99; however, this default may be overridden by either the - 
digits option orbythe -suffix-format option. (See "Options,'' next.) In any case, concatenating the output files in sorted 
order by fi lename produces the original input fi le i n order. T he default output filename prefix isxx. 

By default, if cspiit encounters an error or receives a hangup, interrupt, quit, or terminate signal, it removes any output files 
that it has created so far before it exits. 


OPTIONS 

-f, — prefix=p refi x 

-b, — suffix-format=s iif f i x 


-n, — digit s=di gits 

-k, -keep-files 

-z, —elide-empty-files 


-s, -q, —silent, —quiet 

— help 

— version 


U se pr ef i * as the output fi lename prefix string. 

Usesuf f i x as the output filename suffix string. W hen this option is specified, the suffix string 
must include exactly one printf(3) style conversion specification (such as%d, possibly including 
format specification flags, afield width, a precision specifications, or all of these kinds of 
modifiers). The conversion specification must be suitable for converting a binary integer 
argument to readable form. Thus, only d, i, u, o, x, and x format specifiers are allowed. The 
entire suffix string is given (with the current output file number) to sprintf(3) to form the 
filename suffixes for each of the individual output filesin turn. Note that when this option is 
used, the -digits option is ignored. 

Use output filenames containing numbers that are di gits digits long instead of the default 2. 

D o not remove output files when errors are encountered. 

Suppress the generation of zero-length output files. (In cases where the section delimiters of the 
input file are supposed to mark the first lines of each of the sections, the first output filewill 
generally be a zero-length file uni ess you use this option.) N ote that the output file sequence 
numbers will always run consecutively, starting from 0, even in cases where zero-length output 
sections are suppressed due to the use of this option. 

Do not print counts of output file sizes. 

Print a usage message and exit with a nonzero status. 

Print version information on standard output, then exit. 
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ctags 

ctags- Generates tags and (optionally) refs files 

SYNOPSIS 

ctags [-BSstvraT] fi I esnames... 

DESCRIPTION 

ctags generates the tags and refs files from a group of C source files. The tags file is used by theeivis :tag command, 
control-] command, and -t option. The refsfileissometimes used by the ref(1) program. 

Each C source file is scanned for #define statements and global function definitions. The name of the macro or function 
becomes the name of a tag. For each tag, a line is added to the tags file that contains the following: 

■ The name of thetag 

■ A tab character 

■ Thenameofthefilecontainingthetag 

■ A tab character 

■ A way to find the particular linewithin thefile 

Thefi i enames list will typically be the names of all C source files in the current directory, like this: 

$ ctags -stv *.[ch] 

OPTIONS 

-b N ormally, ctags encloses regular expressions in slashes (/regexp/), which causes eivis to search from the 

top of thefile. The -b flag causes ctags to enclose the regular expressions in question marks (?regexp?) so 
eivis will search backward from the bottom of thefile. This rarely matters. 

-t Includetypedefs. A tag will be generated for each user-defined type. Also tags will be generated for struct 

and enum names. Types are considered to be global if they are defined in a header file, and static if they are 
defined in aC source file. 

-v Include variable declarations. A tag will be generated for each variable, except for those that are declared 

inside the body of a function. 

-s Include static tags, ctags will normally put global tags in the tags file, and silently ignore the static tags. 

This flag causes both global and static tags to be added. The name of astatic tag is generated by prefixing 
the name of the declared item with the nameof thefi le where it is defined, with acolon in between. For 
example, static too (){} in bar.c resultsin atag named bar.citoo. 

-s Include static tags, but make them look like global tags. M ost tags-aware programs don't like the 

filename itagname tags produced by the -s flag, so -s was added as an alternative. If eivis and ret are the 
only programsthat read thetags file, then you don't need -s; otherwise, you do. 

-r This causes ctags to generate both tags and refs. W ithout -r, it would only generate tags. 

-a Append to tags, and maybe refs. N ormally, ctags overwrites these files each time it is invoked. This flag is 

useful when you have too many files in the current directory for you to list them on a single command 
line; it allows you to split theargumentsamong several invocations. 

-t Thisflag isn't available on all systems. U NIX hasit, but most others don't. The -t flag prevents ctags 

from generating a tags file This is useful when you want to generate a refs without changing tags. 


FILES 

tags A cross-reference that lists each tag name, the name of the source file that contains it, and away to locate a 

particular linein the source fi le 

refs The refs file contains the definitions for each tag in thetags file, and very little else. This file can be 

useful, for example, when licensing restrictions prevent you from making the source code to the standard 
C library readable by everybody, but you still want everybody to know what argumentsthe library 
functions need. 



Parti: User Commands 



BUGS 

ctags is sensitive to indenting and line breaks. Consequently, it might not discover all ofthetagsin a filethat isformatted in 
an unusual way. 

SEE ALSO 

elvis(l), nefs(l) 

AUTHOR 

Steve Kirkendall (kirkenda@cs.pdx.edu) 


cu 

cu— Call up another system 

SYNOPSIS 

cu [ cptions ] [ system ] phone | "dir" ] 

DESCRIPTION 

Thecu command is used to call up another system and act as a dial in terminal. It can also do simple file transfers with no 
error checking. 

cu takes a single argument, besides the options. If the argument is the string dir, cu will make a direct connection to the port. 
This may only be used by users with write access to the port, as it permits reprogramming the modem. 

Otherwise, if the argument begins with a digit, it is taken to be a phone number to call. Otherwise, it is taken to be the name 
of a system to call. The -z or - system option may be used to name a system beginning with a digit, and the-c or - phone 
option may be used to name a phone number that does not begin with a digit. 

cu locates a port to use in theUUCP configuration files. If a simple system name is given, it will select a port appropriate for 
that system. The -p, -port, - 1 , -line, -s, and -speed options may be used to control the port selection. 

When a connection ismadeto the remote system, cu forks into two processes. One reads from the port and writes to the 
terminal, whi le the other reads from the terminal and writes to the port. 

cu provides several commands that may beused during the conversation. Thecommands all begin with an escape character, 
initially' (tilde). The escape character is only recognized at the beginning of a line. To send an escape character to the 
remote system at the start of aline it must be entered twice. All commands are either a single character or a word beginning 
with % (percent sign). 

cu recognizesthefollowing commands: 

Terminatetheconversation. 

■| command Run command in a shell. If command isempty, starts up a shell. 

■$ command Run command , sending the standard output to the remote system. 

'! command Run command , taking the standard input from the remote system. 

■+ command Run command , taking the standard input from the remote system and sending the standard 

output to the remote system. 

■#, "%br eak Send a break signal, if possible. 

'c directory, "%cd directory Changethelocal directory. 

■> file Send a file to the remote system. This just dumps the file over the communication line It is 

assumed that the remote system isexpecting it. 

■< Receive a file from the remote system. This prompts for the local filename and for the 

remote command to execute to begin the file transfer. It continues accepting data until the 
contents of the eof read variable are seen. 
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'p from to, '%put from to 

"t from to, ”%take from to 

's variable value 
"! vari abl e 
'z 

'%nostop 

'%stop 

"v 

'? 


escape 

delay 

eol 

binary 

binary-prefix 

echo-check 

echonl 

timeout 

kill 
resend 
eofwrite 
eofread 

verbose 


Send afileto aremoteU NIX system. Thisrunstheappropriatecommandson theremote 
system. 

Retrieve a file from a remoteU NIX system. This runs the appropriate commands on the 
remote system. 

Set acu vari able to th e gi ven value. Ifvaiue is not given, the variable is set to True. 

Set acu vari able to False. 

Suspend thecu session. This is only supported on some systems. On systems for which "z 
may be used to suspend a job, "z will also suspend the session. 

Turn off xon/xoff handling. 

Turn on xon/xoff handling. 

List all the variables and their values. 

List all commands. 

cu also supports sa/eral variables. They may be listed with the v command, and set with the 
”s or ” i commands. 

The escape character. Initially ' (tilde). 

If this vari able is True, cu will delay for a second after recognizing the escape character before 
printing the name of the local system. T he default isTrue. 

The list of characters which are considered to finish aline. The escape character is only 
recognized after one of these is seen. The default iscarriage return, "u, 'c, "o, "d, ~ s , 'q, 'r. 

W hether to transfer binary data when sending a file. Ifthisis False, then newlines in thefile 
being sent are converted to carriage returns The default is False. 

A string used before sending a binary character in a file transfer, if the binary vari able is 
True. The default is ~z. 

W hether to check file transfers by examining what the remote system echoes back. This 
probably doesn't work very well. T he default is False. 

The character to look for after sending each line in a file. The default iscarriage return. 
Thetimeoutto use, in seconds, when looking for a character, either when doingecho 
checki ng or when looking for the echom character. T he default is 30 . 

The character to use to delete a line if the echo check fails The default is"u. 

The number of times to resend a line if the echo check continues to fail. The default is 10 . 
The string to write after sending a file with the ■> command. The default is 'd. 

The string to look for when receiving a file with the •< command. The default is $, which is 
intended to be a typical shell prompt. 

Whether to print accumulated information during a file transfer. The default is True. 


OPTIONS 


The followi ng opti ons may be given to cu: 


-e, —parity=even 

- 0 , —parity=odd 

—parity=none 

-h, —half duplex 

-z system, —system system 

-c phone-number , —phone phone-number 

-p port, —port port 

-a port 

-1 line, —line line 


Use even parity. 

Use odd parity. 

U se no parity. N 0 parity is also used if both -e and -0 are given. 

Echo characters locally (half-duplex mode). 

The system to call. 

Thephonenumber to call. 

Name the port to use. 

Equivalentto -port port. 

N ame the line to use by giving a device name. T his may be used to dial out on 
ports that are not listed in theUU CP configuration files. W rite access to the device 
is required. 
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-s speed, —speed speed 
-# 

-n, —prompt 
-d 

-x type, —debug type 


-I file, —config file 

-v, —version 
— help 


T he speed (baud rate) to use. 

Where# is a number, equivalent to -speed #. 

Prompt for the phone number to use. 

Enter debugging mode. Equivalent to -debug ail. 

T urn on particular debugging types. The following types are recognized: abnormal, 
chat, handshake, uucpproto, proto, port, config, spooldir, execute, incoming, 
outgoing. 0 nly abnormal, chat, handshake, port, config, incoming and outgoing are 
meaningful for cu. M u I tipie types may be given, separated by commas, and the - 
debug option may appear multi pie times. A number may also be given, which will 
turn on that many types from the foregoing list; for example, -debug 2 is 
equivalent to -debug abnormal,chat, -debug ail may be used to turn on all 
debugging options. 

Set configuration file to use. This option may not be available depending upon 
how cu was compiled. 

Report version information and exit. 

Print a help message and exit. 


BUGS 

Thisprogram does not work very well. 

FILES 

The filename may be changed at compilation time, so this is only an approximation. Configuration file 

/usr/lib/uucp/config 


AUTHOR 

Ian LanceTaylor (ian@airs.com) 


Taylor UUCP 1.05 


cut 

cut— Removesectionsfrom each lineof files 

SYNOPSIS 

cut {-b byte-list, —bytes=byt e-I i st} [-n] [—help] [—version] [file...] 

cut {-c character-1 i st , — characte rs=c haracter-l i st} [—help] [—version] [file...] 

cut {-f field-list, —fields=f i el d- 1 i st} [-d del i m] [-s] [—delimiter=d e I i m] 

[-only-delimited] [ — help] [—version] [file...] 

DESCRIPTION 

This manual page documents the GN U version of cut. cut prints sections of each lineof each input file, or the standard 
input if no files are given. A filename of - means standard input. The sections to be printed are selected by the options. 

OPTIONS 

The byte - 1 i st, character - 1 i st, and f i el d-1 i st options are one or more numbers or ranges (two numbers separated by a 
dash) separated by commas. Thefirst byte, character, and field are numbered 1 . Incomplete ranges may be given: -m means 1 - 
m; n- means n through end of line or last field. 
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-b, —bytes byte-1 i st 

-c, —characters character-1 i st 


-f, —fields f i el d-1 i st 
-d, —delimiter del i m 
-n 

-s, -only-delimited 

— help 

— version 


Print only the bytes in positions listed in byte -1 i st . Tabs and backspaces are treated like 
any other character; they take up one byte. 

Print only characters in positions listed in character-iist.T he same as -b for now, but 
internationalization will change that. T abs and backspaces are treated like any other 
character; they take up one character. 

Print only the fields listed infieid-iist. Fields are separated by tab by default. 

For -t, fields are separated by the first character in del i m instead of by tab. 

D o not split multibyte characters (no-op for now). 

For -t, do not print lines that do not contain thefield separator character. 

Print a usage message and exit with a nonzero status. 

Print version information on standard output then exit. 
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CVS 

cvs— C oncurrent V ersions System 

SYNOPSIS 

cvs [ cvs_options ] cvs-command [ command_options ][command_args ] 


DESCRIPTION 

cvs is a front end to the rcs(l) revision control system, which extends the notion of revision control from a collection of files 
in a single directory to a hierarchical collection of directories consisting of revision controlled files. These directories and files 
can be combined together to form a software release, cvs provides the functions necessary to manage these software releases 
and to control the concurrent editing of source files among multiple software developers. 

cvs keeps a single copy of the master sources. This copy is called the source repository, it contains all the information to 
permit extracting previous software releases at any time based on either a symbolic revision tag, or a date in the past. 


ESSENTIAL COMMANDS 


cvs provides a rich variety of commands (cvs_command in the Synopsis), each of which often has a wealth of options, to satisfy 
the many needs of source management in distributed environments. FI owever, you don't have to master every detail to do 
useful work with cvs; in fact, five commands are sufficient to use (and contribute to) the source repository. 


cvs checkout modul es 


cvs update 


cvs add file. 


cvs remove file. 


cvs commit file. 


A necessary preliminary for most cvs work: creates your private copy of the source for 
modules (named collections of source; you can also use a path relative to thesource 
repository here). You can work with this copy without interfering with others' work. At 
least one subdirectory level is always created. 

Execute this command from within your private source directory when you wish to 
update your copies of source files from changes that other developers have made to the 
source in the repository. 

Use this command to enroll new files in cvs records of your working directory. The files 
will be added to the repository the next time you run cvs commit. N ote: You should use 
the cvs import command to bootstrap new sources into the source repository, cvs add is 
only used for new files to an already checked-out module. 

Use this command (after erasing any files listed) to declare that you wish to eliminate 
files from the repository. The removal does not affect others until you run cvs commit. 
Use this command when you wish to "publish'' your changes to other developers, by 
incorporating them in the source repository. 



Parti: User Commands 


FI 

OPTIONS 

T he cvs command line can include cvs_options, which apply to the overall cvs program; a cvs_command, which specifies a 
particular action on the source repository; and command_options and command_arguments to fully Specify what the cvs_command 
will do. 


WARNING 


You must be careful of precisely where you pi ace options relative to the cvs_command.Thesameoption can mean different 
things depending on whether it is in thecvs_options position (to the left of a cvs command) or in thecommand_options 
position (to the right of a cvs command). 


There are only two situations where you may omit cvs_command: cvs -h or cvs -help elicits a list of avail able commands, and 
cvs -v or cvs -version displays version information on cvs itself. 


CVS OPTIONS 


As of release 1.6, cvs supports G N U style long options as well as short options. Only a few long options are currently 
supported; these are listed in brackets after the short options whose functions they duplicate. 


Use these options to control the overall cvs program: 


-H [-help] 


-Q 

-q 

-b bi ndi r 

-d CVS root di rect ory 


-e editor 

-f 

-1 


-n 


-t 


-r 

-v [-version] 
-w 


-z compression-1 evel 


Display usage information about the specified cvs command (but do not actually execute the 
command). If you don't specify a command name, cvs -h displays a summary of all the 
commands available 

Causes the command to be really quiet; the command will generate output only for serious 
problems. 

Causes the command to be somewhat quiet; informational messages, such as reports of 
recursion through subdirectories, are suppressed. 

U se bi ndi r as the directory where RC S programs are located. 0 verrides the setting of the rcsbin 
environment variable. Thisvalue should be specified as an absolute pathname. 

Usecvs_root_di rectory as the root directory pathname of the master RCS source repository. 
Overrides the setting of the cvs -root environment variable. This value should be specified as an 
absolute pathname. 

Useedi tor to enter revision log information. 0 verrides the setting of the cvseditor and the 
editor environment variables. 

Do not read the cvs startup file (' /. cvsrc). 

Do not log thecvs_command in the command history (but execute it anyway). See the descrip¬ 
tion of the history command for information on command history. 

D o not change any tiles. Attempt to execute the cvs_command, but only to issue reports; do 
not remove, update, or merge any existing files, or create any new files. 

T race program execution; display messages showing the steps of cvs activity. Particularly useful 
with -n to explore the potential impact of an unfamiliar command. 

M akes new working files read-only. Same effect as if the cvs -read environment variable is set. 

D i splays version and copyright information for cvs. 

M akes new working files read-write (default). Overrides the setting of the cvsread environment 
variable. 

When transferring files across the network use gzip with compression level compressi on-i evei to 
compress and decompress data as it is transferred. Requires the presence of the G N U gzip 
program in the current search path at both ends of the link. 
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USAGE 

Except when requesting general help with cvs -h, you must specify a cvs_command to cvs to select a specific release control 
function to perform. Each cvs command accepts its own collection of options and arguments H owever, many options are 
available across several commands. You can display a usage summary for each command by specifying the -h option with the 
command. 

CVS STARTUP FILE 

N ormally, when cvs starts up, it reads the .cvsrc file from the home directory of the user reading it. This startup procedure 
can be turned off with the -f flag. 

The .cvsrc file lists cvs commands with a list of arguments, one command per line. For example, the following line in 

.cvsrc! 

diff -c 

will mean that the cvs diff command will always be passed the-c option in addition to any other options that are specified 
in thecommand line (i n thiscase, itwill h ave th e effect of producing context sensitive diffs for all executions of cvs diff). 

CVSCOMMAND SUMMARY 

Here are brief descriptions of all the cvs commands: 

add Add a new file or directory to the repository, pending a cvs commit on the same file. Can only be done 

from within sources created by a previous cvs checkout invocation. Use cvs import to place whole new 
hierarchies of sources under cvs control. (Does not directly affect repository; changes working 
directory.) 

admin Execute RC S control functions on the source repository. (Changes repository directly; uses working 

directory without changing it.) 

checkout M ake a working directory of source files for editing. (C reates or changes working directory.) 

commit Apply to the source repository changes, additions, and deletions from your working directory. 

(C hanges repository.) 

diff Show differences between files in working directory and source repository, or between two revisions in 

source repository. (D oes not change either repository or working directory.) 
export Prepare copies of a set of source fi les for shipment off site. D iffers from cvs checkout in that no cvs 

administrative directoriesare created (and therefore cvs commit cannot be executed from adi rectory 
prepared with cvs export), and a symbolic tag must be specified. (D oes not change repository; creates 
directory similar to working directories). 

history Show reports on cvs commands that you or others have executed on a particular file or directory in the 

source repository. (D oes not change repository or working directory.) H istory logs are kept only if 
enabled by creation of the$cvsR00T/cvsR0OT/history file; seecvs(5). 
import Incorporate a set of updates from off-site into the source repository, as a "vendor branch.” (Changes 

repository.) 

log D isplay RC S log information. (D oes not change repository or working directory.) 

rdiff Prepare a collection of diffs as a patch file between two releases in the repository. (Does not change 

repository or working directory.) 

release Cancel a cvs checkout, abandoning any changes. (Can delete working directory; no effect on 

repository.) 

remove Remove files from the source repository, pending a cvs commit on the same files. (Does not directly 

affect repository; changes working directory.) 

rtag Explicitly specify a symbolic tag for particular revisions of files in the source repository. See also cvs 

tag. (C hanges repository directly; does not require or affect working directory.) 
status Show current status of files: latest version, version in working directory, whether working version has 

been edited and, optionally, symbolic tags in the RC S file (Does not change repository or working 
directory.) 
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Specify a symbolic tag for files in the repository. By default, tags the ra/isionsthat were last synchro¬ 
nized with your working directory. (Changes repository directly; uses working directory without 
changing it.) 

Bring your working directory up to date with changes from the repository. M erges are performed 
automatically when possible; a warning is issued if manual resolution is required for conflicting 
changes. (Changes working directory; does not change repository.) 

COMMON COMMAND OPTIONS 

This section describes the co«imand_options that are available across several cvs commands. N ot all commands support all of 
these options; each option is only supported for commands where it makes sense. H owever, when a command has one of 
these options you can counton the same meaning for the option as in other commands. (Other command options, which 
are listed with the i ndividual commands, may have different meanings from onecvs command to another.) 


tag 

update 


WARNING 


The history command is an exception; it supports many options that conflict even with these standard options 


-d date Use the most recent revision no later than date_spec (a single argument, date description specifying a 

date in the past). A wide variety of date formats are supported by the underlying RCS facilities, similar 
to those described in co(l), but not exactly the same. The date_spec is interpreted as being in the local 
time zone, unless a specific time zone is specified. The specification is "sticky" when you use it to make 
aprivatecopy of a source file; thatis, when you get a working file using -d, cvs records the date you 
specified, so that further updates in the same directory will use the same date (unless you explicitly 
override it; see the description of theupdate command), -d is available with thecheckout, ditt, history, 
export, rdiff, rtag, and update commands. Examples of valid date specifications include the following: 

1 month ago 

2 hours ago 
400000 seconds ago 
last year 

last M onday 
yesterday 
a fortnight ago 
3/31/92 10:00:07 PST 
January 23,1987 10:05pm 
22:00 GMT 

-t When you specify a particular date or tag to cvs commands, they normally ignore files that do not 

contain the tag (or did not exist on the date) that you specified. Use the-t option if you want files 
retrieved even when there isno match forthetagordate. (Themost recent version isused in this 
situation.) -t is available with these commands: checkout, export, rdiff, rtag, and update. 

-h H elp; describe the options avail able for this command. This is the only option supported for all cvs 

commands. 

-k kf i a g Alter the default RCS processing of keywords; all the -k options described in co(l) are available. The -k 

option is available with the add, checkout, diff, export, rdiff, and update commands. Your kf I ag 
specification is "sticky” when you use it to create a private copy of a source file; that is, when you use 
thisoption with thecheckout or update commands, cvs associates your selected kf i ag with thefile, and 
continues to use it with future update commands on the same file until you specify otherwise. 

Some of the more useful kf i ag s are -ko and - kb (for binary files, only compatible with RCS version 5.7 
or later), and -kv, which is useful for an export where you wish to retain keyword information after an 
import at some other site. 
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Local; run only in current working directory, rather than recurring through subdirectories. Available 
with the following commands: checkout, commit, diff, export, remove, rdiff, rtag, status, tag, and 
update. 


WARNING 


T his is not the same as the overall cvs -1 option, which you can specify to the left of a cvs command. 


-n Do not run any checkout/commit/tag/update program. (A program can be specified to run on each of 

these activities, in the modules database; thisoption bypasses it.) Available with thecheckout, commit, 
export, and rtag commands. 


WARNING 


This is not the same as the overall cvs -n option, which you can specify to the left of a cvs command. 


-p Prune (remove) directories that are empty after being updated, on checkout, or update. N ormally, an 

empty directory (onethat is void of revision-controlled files) is left alone Specifying-p will cause these 
directories to be silently removed from your checked-out sources. This does not remove the directory 
from the repository, only from your checked out copy. N ote that this option is implied by the -r or -d 
options of checkout and export. 

-p Pipe the files retrieved from the repository to standard output, rather than writing them in thecurrent 

directory. Available with thecheckout and update commands. 

-r tag U se the revision specified by the tag argument instead of the default head revision. As well as arbitrary 

tagsdefined with thetag or rtag command, two special tags are always available: head refers to the 
most recent version available in the repository, and base refers to the revision you last checked out into 
thecurrent working directory. Thetag specification is "sticky" when you use thisoption with cvs 
checkout or cvs update to makeyour own copy of afile cvs remembers the tag and continues to use it 
on future update commands, until you specify otherwise, tag can be either a symbolic or numeric tag, 
in RC S fashion. Specifying the -q global option along with the -r command option is often useful, to 
suppress the warning messages when the RCS file does not contain the specified tag. -r is avai lable 
With thecheckout, commit, diff, history, export, rdiff, rtag, and update Commands. 


WARNING 


This is not the same as the overall cvs -r option, which you can specify to the left of a cvs command. 


CVS COMMANDS 

H ere (finally) are details on all the cvs commands and the options each accepts. The summary lines at the top of each 

command's description highlight three kinds of things: 

Command Options and Arguments Special options are described in detail; common command options may appear only 

in the summary line. 

Working D irectory, or Repository? Some cvs commands require a working directory to operate; some require a 

repository. Also, some commands change the repository, some change the working 
directory, and some change nothing. 

Synonyms M any commands have synonyms, which you may find easier to remember (or type) 

than the principal name. 
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■ add [-k k f I a g ] [-m 'message'] files... 

Requires: Repository, working directory 

Changes: Working directory 

Synonym: new 

Use the add command to create a new file or directory in the RCS source repository. The files or directories specified with 
add must already exist in the current directory (which must have been created with the checkout command). To add a whole 
new directory hierarchy to the source repository (for example, files received from a third-party vendor), usethecvs import 
command instead. 

If the argument to cvs add refers to an immediate subdirectory, the directory is created at the correct place in the RCS source 
repository, and the necessary cvs administration files are created in your working directory. If the directory already exists in 
the source repository, cvs add still creates the administration files in your version of the directory. This allows you to use cvs 
add to add a particular directory to your private sources a/en if someone else created that directory after your checkout of the 
sources. You can do the following: 

example% mkdir new_directory 
example% cvs add new_directory 
example% cvs update new_directory 

An alternate approach using cvs update might be: 
example% cvs update -d new_directory 

(To add any available new directoriesto yourworking directory, it's probably simpler to use cvs checkout or cvs update -d.) 

The added files are not placed in the RCS source repository until you use cvs commit to make the change permanent. Doing 
acvs add on afile that was removed with thecvs remove command will resurrect thefile, if no cvs commit command 
intervened. 

You will have the opportunity to specify a logging message, as usual, when you use cvs commit to make the new file 
permanent. If you'd like to have another logging message associated with just creation of the file (for example, to describe the 
file's purpose), you can specify it with the -m message option to the add command. 

The -k kf i ag option specifies thedefault way that thisfile will be checked out. Thekf i ag argument is stored in the RC S file 
and can be changed with cvs admin. Specifying -ko is useful for checking in binaries that shouldn't have the RCS id strings 
expanded. 

■ admin [rcs-opti ons ] files... 

Requires: Repository, working directory 

Changes: Repository 

Synonym: res 

This isthe cvs interface to assorted administrative RCS facilities, documented in rcs(l). cvs admin simply passes all its 
optionsand arguments to thercs command; it does no filtering or other processing. This command does work recursively, 
however, so extreme care should be used. 

■ checkout [options] modules... 

Requires: Repository 

Changes: Working directory 

Synonyms co, get 

M ake a working directory containing copies of the source files specified by modules. You must execute cvs checkout before 
using most of the other cvs commands, since most of them operate on yourworking directory. 

mod u i es are either symbolic names [them selves defined as the module modules in the source repository; seecvs(5)] for some 
collection of source directories and files, or pathsto directories or files in the repository. 

Depending on the modules you specify, checkout may recursively create directories and populate them with the appropriate 
source files. You can then edit these source files at any time (regardless of whether other software developers are editing their 
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own copies of the sources); update them to include new changes applied by others to the source repository; or commit your 
work as a permanent change to the RC S repository. 

N otethat checkout is used to create directories. The top-level directory created is always added to the directory where 
checkout is invoked, and usually has the same name as the specified module. In the case of a module alias, the created 
subdirectory may have a different name, but you can be sure that it will be a subdirectory, and that checkout will show the 
relative path leading to each file as it is extracted into your private work area (unless you specify the -q global option). 

Running cvs checkout on a directory that was already built by a prior checkout is also permitted, and has the same effect as 
specifying the -d option to the update command described later. 

The options permitted with cvs checkout include the standard command options -p, -f, -k ktiag, -1, -n, -p, -r tag, and -d 
date. In addition to those, you can use several special command options with checkout, as detailed in the following para¬ 
graphs. 

Use the -a option to reset any sticky tags, dates, or -k options. (If you get a working file using one of the -r, -d, or -k 
options, cvs remembers the corresponding tag, date, or ktiag and continues using it on future updates; use the -a option to 
make cvs forget these specifications, and retrieve the head version of the file). 

The-j branch option merges the changes made between the resulting revision and the revision that it is based on (for 
example, if the tag refers to a branch, cvs will merge all changes made in that branch into your working file). 

With two -j options, cvs will merge in the changes between the two respective revisions. This can be used to "remove" a 
certain delta from your working file. 

In addition, each -j option can contain on optional date specification which, when used with branches, can limit the chosen 
revision to one within a specific date. An optional date is specified by adding a colon (:) to the tag. An example might be 
what cvs import tellsyou to do when you havejust imported sources that have conflicts with local changes: 
example% cvs checkout -jTAG:yesterday -jTAG module 

Use the -n option with -d dir to avoid shortening module paths in your working directory. (N ormally, cvs shortens paths as 
much as possible when you specify an explicit target directory.) 

Use the -c option to copy the module file, sorted, to the standard output, instead of creating or modifying any files or 
directories in yourworking directory. 

Usethe-d dir option to create a directory called di r for theworking files, instead of using themodule name Unlessyou 
also use-N, the paths created under dir will be as short as possible. 

Use the -s option to display per-module status information stored with the-s option within the modules file. 

■ commit [-InR] [-m ' logjnessage 1 | -f file] [ -r revision][f i I es ... ] 

Requires: Workingdirectory, repository 

Changes: Repository 

Synonym: ci 

Use cvs commit when you want to incorporate changes from your working source files into the general source repository. 

If you don't specify particular files to commit, all ofthefilesin your working current directory are examined, commit is 
careful to change in the repository only those files that you have really changed. By default (or if you explicitly specify the -r 
option), filesin subdirectories are also examined and committed if they have changed; you can usethe-i option to limit 
commit to thecurrent directory only. Sometimes you maywantto forceafileto be committed even though it is unchanged; 
this is achieved with the -t flag, which also has the effect of disabling recursion (you can turn it back on with -r, of course). 

commit verifies that the selected files are up-to-date with thecurrent revisions in the source repository; it will notify you, and 
exit without committing, if any of the specified files must be made current first with cvs update, commit does not call the 
update command for you, but rather I eaves that for you to do when the time is right. 

When all is well, an editor is invoked to allow you to enter a log message that will be written to one or more logging 
programs and placed in the RCS source repository file. You can instead specify thelog messageon the command linewith 
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the-m option, thus suppressing the editor invocation, or use the -f option to specify that the argument file contains the log 
message. 

The -r option can be used to commit to a particular symbolic or numeric revision within the RCS file. For example to bring 
all your files up to the RCS revision 3.0 (including those that haven't changed), you might use 

example% cvs commit -r3.0 

cvs will only allow you to commit to a revision that is on the main trunk (a revision with a single dot). H owever, you can 
also commit to a branch revision (one that has an even number of dots) with the -r option. T o create a branch revision, one 
typically use the -b option of thertag or tag commands. Then, either checkout or update can be used to base your sources on 
the newly created branch. From that point on, all commit changes made within these working sources will be automatically 
added to a branch revision, thereby not perturbing mainline development in anyway. For example, if you had to create a 
patch to the 1.2 version of the product, even though the 2.0 version is already under development, you might use this: 

example% cvs rtag -b -rFCS1_2 FCS1_2 Patch product_module 
example% cvs checkout -rFCS1_2_Patch product module 
example% cd product module 
[[ hack away ]] 
example% cvs commit 

Say you have been working on some extremely experimental software, based on whatever revision you happened to checkout 
last week. If others in your group would like to work on this software with you, but without disturbing mainline da/elop- 
ment, you could commit your change to a new branch. Others can then check out your experimental stuff and utilize the full 
benefit of cvs conflict resolution. The scenario might look like this: 

example% cvs tag -b EXPR1 
example% cvs update -rEXPRI 
[[ hack away ]] 
example% cvs commit 

Others would simply do cvs checkout -texpri whatever, mod u i e to work with you on the experimental change. 

■ diff [ -kl] [rcsdi ffopti ons ][[-r revl j -D dat el ] [ - r r e v 2 j -D d a t e 2 ] ] [files...] 

Requires: Working directory, repository 

Changes: Nothing 

You can compare your working files with revisions in the source repository, with the cvs diff command. If you don't specify 
a particular revision, your files are compared with the revisions they were based on. You can also use the standard cvs 
command option -r to specify a particular revision to compare your files with. Finally, if you use -r twice, you can see 
differences between two revisions in the repository. You can also specify -d options to diff against a revision in the past. The 
-r and -d options can be mixed together with at most two options ever specified. 

See rcsdiff(l) for a list of other accepted options. 

If you don't specify any files, diff will display differences for all those files in the current directory (and its subdirectories, 
unless you use the standard option - 1 ) that differ from the corresponding revision in the source repository (that is, files that 
you have changed), or that differ from the revision specified. 

■ export [-f INnQq] -r rev ] -D date [-d dir][-k kflag] module... 

Requires: Repository 

Changes: Current directory 

This command is a variant of cvs checkout; use it when you want a copy of the source for model e without the cvs administra¬ 
tive directories. For example, you might use cvs export to prepare source for shipment off-site. This command requires that 
you specify a date or tag (with -d or -r), so that you can counton reproducing the source you ship to others. 

Theonly nonstandard options are-d dir (write the source into directory di r ) and -n (don'tshorten module paths). These 
have the same meanings as the same options in cvs checkout. 
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The-kv option is useful when export is used. Thiscausesany RCS keywords to be expanded such that an import done at 
some other site will not lose the keyword revision information. Otherkf i ag options may be used with cvs export and are 
described in co(l). 

■ history [-report ][—flags][—opti ons args ] [fiI es ... ] 

Requi res: T hefile $cvsR 00 T/cvsR 00 T/history 

Changes: Nothing 

cvs keeps a history file that tracks each useof thecheckout, commit, rtag, update, and release commands. You can use cvs 
history to display this information in various formats. 


WARNING 


cvs history uses-t, -l, -n, and -p in ways that conflict with the descriptions in "Common Command Options," earlier 
in this manual page. 


Several optionsfshown as [-report ] in the precedi ng bullied codeline) control what kind of report isgenerated: 

-c Report on each time commit was used (that is, each time the repository was modified). 

-m modui e Report on a particular module. (You can meaningfully use-m more than once on the command line.) 

-o Report on checked-out modules. 

-t Report on all tags. 

-x type Extract a particular set of record types x from the cvs history. T he types are indicated by single letters, 

which you may specify in combination. Certain commands have a single record type: check-out (type 
o), release (type f), and rtag (type t). 0 ne of four record types may result from an update: w, when the 
working copy of a file is deleted during update (because it was gone from the repository); u, when a 
working file was copied from the repository; g, when a merge was necessary and it succeeded; and c, 
when a merge was necessary but collisions were detected (requiring manual merging). Finally, one of 
three record types results from commit: m, when a file was modified; a, when a file is first added; and r, 
when a file is removed. 

-e Everything (all record types); equivalent to specifying -xmacfrogwut. 

-z zone Usetimezonezone when outputting history records. Thezonenameu standsfor local time; numeric 

offsets stand for hours and minutes ahead of UTC. For example, +0530 standsfor 5 hours and 30 
minutes ahead of (that is, east of) UTC. 


The options shown as -f 1 ags constrain the report without requiring option arguments: 

-a Show data for all users. (The default is to show data only for the user executing cvs history.) 

-1 Show last modification only. 

-w Show only the records for modifications done from the same working directory where cvs history is 

executing. 


Theoptionsshown as-opti ons args constrain thereport based on an argument: 


-b st r 


-D date 


Show data back to a record containing the string str in either the module name, the filename, or the 
repository path. 

Show data sincedate. 


-p repository Show data for a particular sourcerepository (you can specify several -p options on the same command 
line). 

-r rev Show records referring to revisions si nee the revision or tag named r ev appears in individual RCSfiles. 

Each RCS file is searched for the revision ortag. 

-t tag Show records si nee tag tag was last added to the history file. This differs from the - r flag in that it 

reads only the history file, not the RCS files, and ismuch faster. 

-u name Show recordsfor username. 
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■ import [-options] repository vendortag releasetag ... 

Requires: Repository, source distribution directory 

Changes: Repository 

Use cvs import to incorporate an entire source distribution from an outside source (for example, a source vendor) into your 
source repository directory. You can use this command both for initial creation of a repository, and for wholesale updates to 
themoduleform the outside source. 

The repository argument gives a directory name (or a path to a directory) under the CVS root directory for repositories; if 
the directory did not exist, import creates it. 

When you use import for updates to source that has been modified in your source repository (si nee a prior import), it will 
notify you of any files that conflict in the two branches of development; use cvs checkout -j to reconcile the differences, as 
import instructs you to do. 

By default, certain filenames are ignored during cvs import: names associated with CVS administration, or with other 
common source control systems; common names for patch files, object files, archive files, and editor backup files; and other 
names that are usually artifacts of assorted utilities. Currently, the default list of ignored files includes files matching these 
names: 

RCSLOG RCS SCCS 
CVS* cvslog.* 
tags TAGS 

.make.state .nse_depinfo 
’ #* .#* , 

.old *.bak *.BAK *.orig *.rej .del-* 

.a *.o *.so *.Z *.elc *.ln core 

The outside source is saved in a first-level RCS branch, by default 1 . 1 . 1 . U pdates are I eaves of this branch; for example, files 
from the first imported collection of source will be revision 1 . 1 . 1 . 1 , then files from the first imported update will be revision 
1 . 1 . 1 . 2 , and so on. 

At least three arguments are required, repository is needed to identify the collection of source, vendortag is a tag for the 
entire branch (for example, fori. 1 . 1 ). You must also specify at least one releasetag to identify the files at the leaves created 
each ti me you execute cvs import. 

One of the standard cvs command options is available: -m message. If you do not specify a logging message with -m, your 
editor isinvoked (aswith commit) to allow you to enter one. 

There are three additional special options 

Use-d to specify that each file'stimeof last modification should be used for thecheckin date and time. 

Use-b branch to specify a first-level branch other than 1 . 1 . 1 . 

Use-i name to specify filenames that should be ignored during import. You can usethisoption repeatedly. To avoid 
ignoring any files at all (even those ignored by default), specify -1 !. 

■ log [-1] rlog-options [files...] 

Requires: Repository, working directory 

Changes: Nothing 

Synonym: riog 

D isplay log information form es. cvs log calls the RCS utility riog; all the options described in riog(l) are available. 
Among the more useful riog options are -h to display only the header (including tag definitions, but omitting most of the 
full log); -r to select logs on particular revisions or ranges of revisions; and -d to select particular dates or date ranges. See 
riog(l) for full explanations. Thiscommand is recursive by default, unless the-i option is specified. 
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■ rdiff [-fIags][-V vn] [-r t |-D d [-r 121-D d2]] moduI es ... 

Requires: Repository 

Changes: Nothing 

Synonym: patch 

Builds a Larry Wall format patch(l) file between two releases that can be fed directly into the patch program to bring an old 
release up-to-date with thenew release. (Thisisoneof thefew cvs commands that operatesdirectly from the repository and 
doesn't require a prior checkout.) The ditt output is sent to the standard output device. You can specify (using the standard 
-r and -d options) any combination of one or two revisions or dates. If only one revision or date is specified, the patch file 
reflects differences between that revision or date and the current head revisions in the RCS file. 

N otethat if the software release affected is contained in more than one directory, then it may be necessary to specify the-p 
option to the patch command when patching the old sources, so that patch is able to find the files that are located in other 
di recto ri es. 

If you use the option -v vn, RCS keywords are expanded according to the rules current in RCS version vn (the expansion 
format changed with RCS version 5). 

The standard option flags -f and -i are available with this command. There are also several special optionsf lags. 

If you usethe-s option, no patch output isproduced. Instead, a summary of thechanged or added files between thetwo 
releases is sent to the standard output device. This is useful for finding out, for example, which files have changed between 
two dates or revisions. 

If you use the-t option, a ditt of the top two revisions is sent to the standard output device. This is most useful for seeing 
what the last change to afilewas. 

If you usethe-u option, thepatch output uses the newer uniditf format for context difts. 

You can use -c to explicitly specify the diff -c form of context difts (which is the default), if you like. 

■ release [-dQq] modules... 

Requires: W orking directory 

Changes: Working directory, history log 

This command is meant to safely cancel the effect of cvs checkout. Si nee cvs doesn't lock files, it isn't strictly necessary to use 
this command. You can always simply delete your working directory, if you like; but you risk losing changes you may have 
forgotten, and you leave no trace in the cvs history file that you've abandoned your checkout. 

Use cvs release to avoid these problems. T his command checks that no uncommitted changes are present; that you are 
executing it from immediately above, or inside, aevs working directory; and that the repository recorded for your files is the 
same as the repository defined in the module database. 

If all these conditions are true, cvs release leaves a record of its execution (attesting to your intentionally abandoning your 
checkout) in the cvs history log. 

You can use the -d flag to request that your working copies of the source files be deleted if the release succeeds. 

■ remove [-1R ] [files...] 

Requires: Working directory 

Changes: Working directory 

Synonyms: rm, delete 

Use this command to declare that you wish to removefiles from the source repository. Like most cvs commands, cvs remove 
works on files in your working directory, not directly on the repository. As a safeguard, it also requires that you first erase the 
specified files from your working directory. 

Thefilesarenot actually removed until you apply your changes to the repository with commit; at that point, the correspond¬ 
ing RCS files in the source repository are moved into the Attic directory (also within the source repository). 



Parti: User Commands 



This command is recursive by default, scheduling all physically removed files that it finds for removal by the next commit. U se 
the-i option to avoid this recursion, or just specify that actual files that you wish remove to consider. 

■ rtag [-f alnRQq] [-b][ -d ][ -r tag j -D date] symbol i c_tag modu I es .. . 

Requires: Repository 

Changes: Repository 

Synonym: rfreeze 

You can use this command to assign symbolic tags to particular, explicitly specified source versions in the repository, cvs 
rtag works directly on the repository contents (and requires no prior checkout). Use cvs tag instead, to base the selection of 
versions to tag on the contents of your working directory. 

In general, tags (often the symbolic names of software distributions) should not be removed, but the-d option is available as 
a means to remove completely obsolete symbolic names if necessary (as might be the case for an Alpha release, say). 

cvs rtag will not move a tag that already exists. W ith the-F option, however, cvs rtag will relocate any instance of 
symbolictag that already exists on that file to the new repository versions. Without the-F option, attempting to use cvs 
rtag to apply a tag that already exists on that file will produce an error message. 

The -b option makes the tag a branch tag, allowing concurrent, isolated development. This is most useful for creating a patch 
to a previously released software distribution. 

You can use the standard -r and -d options to tag only those files that already contain a certain tag. This method would be 
used to rename a tag: tag only the files identified by the old tag, then delete the old tag, leaving the new tag on exactly the 
same files as the old tag. 

rtag executes recursively by default, tagging all subdirectories of modules you specify in the argument. You can restrict its 
operation to top-level directories with the standard -1 option; or you can explicitly request recursion with -r. 

The modules database can specify a program to execute whenever a tag is specified; atypical use is to send electronic mail to 
a group of interested parties. If you want to bypass that program, use the standard -n option. 

Use the -a option to have rtag look in the Attic for removed files that contain the specified tag. The tag is removed from 
these files, which makes it convenient to reuse a symbolic tag as development continues (and files get removed from the 
upcoming distribution). 

■ status [-lRqQ] [-v][fi I es ...] 

Requires: Working directory, repository 

Changes: Nothing 

Display a brief report on the current status of files with respect to the source repository, including any sticky tags, dates, or-k 
options. (Sticky optionswill restrict how cvs update operates until you reset them; see the description of cvs update -a.... 

You can also use this command to anticipate the potential impact of a cvs update on your working source directory. If you 
do not specify any files explicitly, reports are shown for all files that cvs has placed in your working directory. You can limit 
the scope of this search to the current directory itself (not its subdirectories) with the standard -1 option flag; or you can 
explicitly request recursive status reports with the-R option. 

The-v option causes the symbolic tags for the RC S fi le to bedisplayed as well. 

■ tag [-lQqR][-F][-b][-d][-r tag | -D d a t e][-f] symbolic_tag [files ...] 

Requires: Working directory, repository 

Changes: Repository 

Synonym: freeze 

Use this command to assign symbolic tags to the nearest repository versions to your working sources. The tags are applied 
immediately to the repository, as with rtag. 0 ne use for tags is to record a "snapshot" of the current sources when the 
software freeze date of a project arrives. As bugs are fixed after the freeze date, only those changed sources that are to be part 
of the release need be retagged. 
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The symbolic tags are meant to permanently record which revisions of which files were used in creating a software distribu¬ 
tion. The checkout, export, and update commands allow you to extract an exact copy of a tagged release at any time in the 
future regardless of whether files have been changed, added, or removed since the release was tagged. 

You can use the standard -r and -d options to tag only those files that already contain a certain tag. This method would be 
used to rename a tag: tag only the files identified by the old tag, then delete the old tag, leaving the new tag on exactly the 
samefilesastheold tag. 

Specifying the -t flag in addition to the -r or -d flags will tag those files named on the command line even if they do not 
contain the old tag or did not exist on the specified date. 

By default (without a -r or -d flag), the versions to be tagged are supplied implicitly by thecvs records of your working files' 
history rather than applied explicitly. 

Ifyou use cvs tag -d symbolic tag .... the symbolic tag you specify is deleted i nstead of bei ng added. 


WARNING 


Be very certain of your ground before you delete a tag; doing this effectively discards some historical information, which 
may later turn out to have been valuable. 


cvs tag will not move a tag that already exists. With the-F option, however, cvs tag will relocate any instance of symbolic 
tag that already exists on that file to the new repository versions. Without the-F option, attempting to use cvs tag to apply a 
tag that already existson thatfilewill produce an error message. 

The -b option makes the tag a branch tag, allowing concurrent, isolated development. This is most useful for creating a patch 
to a pra/iously released software distribution. 

N ormally, tag executes recursively through subdirectories; you can prevent this by using the standard -1 option, or specify 
therecursion explicitly by using -r. 

■ update [—Adf IPpQqR][-d][-r tag j —D date] files... 

Requires: Repository, working directory 

Changes: Working directory 

After you've run checkout to create your private copy of source from the common repository, other developers will continue 
changing the central source From time to time when it is convenient in your development process, you can use the update 
command from within your working directory to reconcile your work with any revisions applied to the source repository 
si nee your last checkout or update. 

update keeps you informed of its progress by printing a line for each file, prefaced with one of the characters u, a, r, m, c, or ? 
to indicate the status of thefile: 

u file The file was brought up-to-date with respect to the repository. This is done for any file that exists in 

the repository but not in your source and for files that you haven't changed but are not the most 
recent versions available in the repository. 

a f i i e The file has been added to your private copy of the sources, and will be added to the RCS source 

repository when you run cvs commit on thefile. This is a reminder to you that the file needs to be 
committed. 

r file Thefile has been removed from your private copy of the sources, andwill be removed from the RCS 

source repository when you run cvs commit on thefile. This is a reminder to you that the file needs to 
be committed. 

m f i i e The file is modified in your working directory, m can indicate one of two states for a file you're working 

on: either there were no modifications to the same file in the repository, so that your file remains as 
you last saw it; or there were modifications in the repository as well as in your copy, but they were 
merged successfully, without conflict, in your working directory. 
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c f i i e A conflict was detected while trying to merge your changes to f i i e with changes from the source 

repository, file (the copy in your working directory) is now the output of thercsmerge(l) command 
on the two versions; an unmodified copy of your file is also in your working directory, with the name 
,#tiie. version, where version is the RC S revision that your modified file started from. (N otethat 
some systems automatically purge files that begin with .# if they have not been accessed for a few days. 
If you intend to keep a copy of your original file, it is a very good idea to rename it.) 

? f i i e file is in your working directory, but does not correspond to anything in the source repository, and is 

notin the list of files for cvs to ignore; see the description of the-i option. 

Use the -a option to reset any sticky tags, dates, or-k options. (If you get a working copy of a file by using one of the -r, -d, 
or-k options, cvs remembers the corresponding tag, date, or ktiag and continues using it on future updates; use the -a 
option to make cvs forget these specifications, and retrieve the head version of the file). 

T he -jbranch option merges the changes made between the resulting revision and the revision that it is based on. (For 
example, if the tag refers to a branch, cvs will merge all changes made in that branch into your working file.) 

With two -i options, cvs will merge in the changes between the two respective revisions. This can be used to "remove" a 
certain delta from your working file. For example, ifthefiletoo.c isbased on revision 1.6 and I want to remove the changes 
made between 1.3 and 1.5,1 might do this: 
example% cvs update -j1.5 -j1.3 foo.c # note the order... 

In addition, each -j option can contain on optional date specification which, when used with branches, can limit the chosen 
revision to onewithin a specific date. An optional date is specified by adding a colon (:) to thetag: 

-jSymbolic Tag:Date Specifier 

U sethe-d option to create any directories that exist in the repository if they're missing from the working directory. 

(N ormally, update acts only on directories and files that were already enrolled in your working directory.) This is useful for 
updating directories that were created in the repository si nee the initial checkout; but it has an unfortunate side effect. If you 
deliberately avoided certain directories in the repository when you created your working directory (either through use of a 
module name or by listing explicitly the files and directories you wanted on the command line), then updating with -d will 
create those directories, which may not be what you want. 

Use-i name to ignore fi les whose names match name (in your working directory) during the update. You can specify-i more 
than onceon thecommand lineto specify several files to ignore By default, update ignores files whose names match any of 
thefollowing: 

RCSLOG RCS SCCS 
CVS* cvslog.* 
tags TAGS 

.make.state .nse_depinfe 
" #* .#* , 

.old *.bak *.BAK *.orig *.rej .del-* 

.a *.o *.so *.Z *.elc *.ln cone 

Use-n to avoid ignoring any files at all. 

Thestandard cvs command options -f, -k, - 1 , -p, -p, and -r arealso available with update. 

FILES 

For more detailed information on cvs supporting files, seecvs(5). 

Files in home directories: 

.cvsrc The cvs initialization file. Lines in this file can be used to specify default options for each cvs 

command. For example the li neditf -c will ensure that cvs diff is always passed the-c option in 
addition to any other options passed on thecommand line. 

.evswrappers Specifies wrappers to be used in addition to those specified in thecvsROOT/cvswrappers filein the 

repository. 



Files in working directories: 

CVS 

CVS/Entries 
CVS/Entries.Backup 
CVS/Entries.Static 
CVS/Root 


CVS/Repository 
CVS/Tag 

CVS/Checkin.prog 

CVS/Update.prog 

Files in source repositories: 

$CVSR00T/CVSROOT 
CVSROOT/commitinfo, v 
CVSROOT/cvswrappers,v 


CVSROOT/editinfo,v 

CVSROOT/history 

CVSROOT/loginfo,v 

CVSROOT/modules,v 

CVSROOT/rcsinfo,v 

CVSROOT/taginfOjV 

MODULE/Attic 

#cvs.lock 

#cvs.tfl.pid 

#cvs.rfl.pid 

#cvs.wfl.pid 

ENVIRONMENT VARIABLES 

CVSROOT 


CVSREAD 

RCSBIN 

CVSEDITOR 

CVS_IGNORE_REMOTE_ROOT 


CVS 



A directory of cvs administrative files. Do not delete. 

List and status of files in your working directory. 

A backup Of CVS/Entries. 

Flag: do not add more entries on cvs update. 

Pathname to the repository (cvsroot) location at the time of checkout. This file is used instead 
of the cvsroot environment variable if the environment variable is not set. A warning message 
will be issued when the contents of thisfile and the cvsroot environment variable differ. The 
file may be overridden by the presence of thecvs_iGN0RE_REM0TE_R00T environment variable. 
Pathname to the corresponding directory in the source repository. 

C ontainsthe per-directory sticky tag or date information. Thisfile is created/updated when you 
specify -r or -d to the checkout or update commands, and no files are specified. 

N ameof program to run on cvs commit. 

N ame of program to run on cvs update. 


D i rectory of global administrative files for repository. 

Records programs forfiltering cvs commit requests. 

Records cvs wrapper commands to beused when checking files into and out of the repository. 
W rappers allow the file or directory to be processed on the way in and out of cvs. The intended 
uses are many; one possible use would be to reformat a C file before the file is checked in, so all 
of the code in the repository looks the same. 

Records programs for editing/validatingcvs commit log entries. 

Log file of cvs transactions. 

Records programs for piping cvs commit log entries. 

Definitions for modules in this repository. 

Records pathnames to templates used during a cvs commit operation. 

Records programs for validating/logging cvs tag and cvs rtag operations. 

D i rectory for removed source files. 

A lock directory created by cvs when doing sensitive changes to theRCS source repository. 

T emporary lock filefor repository. 

A read lock. 

A write lock. 


Should contain the full pathname to the root of the cvs source repository (where theRCS files 
are kept). This information must be available to cvs for most commands to execute; if cvsroot 
is not set, or if you wish to override it for one invocation, you can supply it on the command 
line cvs -d cvsroot cvs command. ... You may not need to set cvsroot if your cvs binary has the 
right path compiled in; usecvs -v to display all compiled-in paths. 

If this is set, checkout and update will try hard to make the files in your working directory read¬ 
only. W hen this is not set, the default behavior is to permit modification of your working files. 
Specifies the full path name where to find RCS programs, such asco(l)and ci(l). If not set, a 
compiled-in valueisused; seethedisplay from cvs -v. 

Specifies the program to use for recording log messages during commit. If not set, the editor 
environment variable is used instead. If editor is not set either, the default is/usr/ucb/vi. 

If this variable is set, then cvs will ignore all references to remote repositories in thecvs/Root 
file. 
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cvs_rsh cvs uses the contents of this variable to determine the name of the remote shell command to use 

when starting a cvs server. If thisvariable is not set then rsh is used. 
cvs_server cvs uses the contents of this vari able to determine the name of the cvs server command. If this 

variable is not set then cvs is used. 

cvswrappers This variable is used by the cvswrappers script to determine the name of the wrapper file, in 

addition to the wrappers defaults contained in the repository (cvsRooi/cvswrappers) and the 
user's home directory (■ / .cvswrappers). 


AUTHORS 

D ick Grune 

Brian Berliner 
Jeff Polk 


Original author of the cvs shell script version posted to comp, sources, unix in thevolume6 
release of D ecember, 1986. Credited with much of the cvs conflict resolution algorithms. 
Coderand designer of the cvs program itself in April, 1989, based on the original work done by 
Dick. 

H elped Brian with the design of the cvs module and vendor branch support and author of the 
checkin (1) Shell Script (the ancestor Of cvs import). 


SEE ALSO 

ci(l), co(l), cvs(5), cvsbug(8), diff(l), grep(l), patch(l), rcs(l), rcsdiff(l), rcsmerge(l), rlogbug(8) 


13 March 1996 


date 

date— Show and set date and time 

SYNOPSIS 

date [ -u ] [—c ][-n ][-d dsttype ] [ -t mi nutes-west ] [ -a [ + j-]sss.fff ][+format ][ 

[yyyy ]mmddhhmm[yy ] [. ss ] ] 

DESCRIPTION 

Datewithout arguments writes thedate and time to the standard output in theform: 

Wed Mar 8 14:54:40 EST 1989 

with est replaced by the local timezone'sabbra/iation (or by the abbreviation for the time zone specified in theiz environ¬ 
ment variable if set). T he exact output format depends on the locale. 

If a command-line argument starts with a plus sign (+), the rest of the argument is used as a format that controls what 
appears in the output. In the format, when a percent sign (%) appears, it and the character after it are not output, but rather 
identify part of the date or time to be output in a particular way (or identify a special character to output): 


Argument 

Sample output 

Explanation 

%3 

Wed 

Abbreviated weekday name* 

%A 

Wednesday 

Full weekday name* 

%b 

Mar 

Abbreviated month name* 

%B 

March 

Full month name* 

%c 

Wed Mar 08 14:54:40 1989 

Date and time* 

%C 

19 

C entury 

%d 

08 

D ay of month (always two digits) 

%D 

03/08/89 

M onth/day/year (eight characters) 
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Argument 

Sampleoutput 

Explanation 

%6 

8 

D ay of month (leading zero blanked) 

%h 

Mar 

Abbreviated month name? 

%H 

14 

24-hour-clock hour (two digits) 

%I 

02 

12 -hour-clock hour (two digits) 

%j 

067 

Julian day number (three digits) 

%k 

2 

12 -hour-clock hour (leading zero blanked) 

%1 

14 

24-hour-clock hour (leading zero blanked) 

%m 

03 

M onth number (two digits) 

%M 

54 

M inute(two digits) 

%n 

nn 

N ewline character 

%p 

PM 

AM/PM designation 

%r 

02:54:40 PM 

Hour:minutesecondAM/PM designation 

%R 

14:54 

H ounminute 

%S 

40 

Second (two digits) 

%t 

nt 

T ab character 

%T 

14:54:40 

H ounminutesecond 

%U 

10 

Sunday-based week number (two digits) 

%w 

3 

Day number (one digit, Sunday isO) 

%W 

10 

M onday-based week number (two digits) 

%x 

03/08/89 

Date* 

%X 

14:54:40 

Time* 

%y 

89 

Last two digits of year 

%Y 

1989 

Year in full 

%Z 

EST 

Time zone abbreviation 

%+ 

Wed Mar 8 14:54:40 EST 1989 

D efault output format* 

* T he exact output depends on the locale. 



If a character other than one of those shown in the preceding table appears after a percent sign in the format, that following 
character is output. All other characters in the format are copied unchanged to the output; a newline character is always 
added at the end of the output. 

In Sunday-based week numbering, the first Sunday of the year begins week 1; days preceding it are part of week 0. In 
M onday-based week numbering, the first M onday of the year begins week 1. 


T o set the date, use a command-line argument with one of the following forms: 

1454 24-hour-dock hours (first two digits) and minutes 

081454 M onth day (first two digits), hours, and minutes 

03081454 M onth (two digits, January is 01), month day, hours, minutes 

8903081454 Year, month, month day, hours, minutes 

0308H5489 M onth, month day, hours, minutes, year (on System V-compatible systems) 

030814541989 M onth, month day, hours, minutes, four-digit year 

198903081454 Four-digit year, month, month day, hours, minutes 
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If the century, year, month, or month day is not given, the current value is used. Any of the preceding forms may be 
followed by a period and two digits that give the seconds part of the new time; if no seconds are given, zero is assumed. 


T hese options are available: 


-u or -c 
-n 

-d dsttype 


-t mi nut es- west 


-a adj ustment 


UseGMT when setting and showing the date and time. 

Do not notify other networked systemsof the time change. 

Set the kernel-stored Daylight SavingTime type to thegiven value. (The kernel-stored DST type is 
used mostly by "old" binaries.) 

Set the kernel-stored "minuteswest of GMT" value to theonegiven on the command line. (The 
kernel-stored DST type is used mostly by "old" binaries.) 

Change the time forward (or backward) by the number of seconds (and fractions thereof) specified 
in the adjustment argument. Either the seconds part or the fractions part of the argument (but not 
both) may be omitted. On BSD-based systems, the adjustment is made by changing the rate at 
which time advances; on System-V-based systems, the adjustment is made by changing the time. 


FILES 

/usr/lib/locale/L/LC TIME 
/usr/local/etc/zoneinfo 
/usr/local/etc/zoneinfo/localtime 
/usr/local/etc/zoneinfo/posixrules 

/usr/local/etc/zonei nfo/G M T 


Description of time locale l 
Timezoneinformation directory 
Local timezonefile 
Used with POSIX-styleTZs 
ForUTC leap seconds 


If /usr/local/etc/zoneinfo/GMT is absent, U T C leap seconds are loaded from /usr/local/etc/zoneinfo/posixrules. 
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dd— Convert a file while copying it (data dumper) 

SYNOPSIS 

dd [—help] [—version] [ if =f i I e ] [ of=f i I e ] [ibs=bytes] [obs=bytes] [bs=bytes] 
[cbs=bytes] [skip=bl ocks ] [seek=bl ocks ] [count=bl ocks ] [conv={ascii, 
ebcdic, ibm, block, unblock, lease, ucase, swab, noerror, notrunc, sync}] 


DESCRIPTION 

This manual page documents the GN U version of dd. dd copies a file (from the standard input to the standard output, by 
default) with a user-selectable blocksize, while optionally performing conversions on it. 


OPTIONS 

Numbers can be followed by a multiplier: 

b=512, c=1, k=1024, w=2, xm=number m 


T hese options are available: 

— help 

— version 
if =f i I e 
of =f i I e 

ibs=byt es 
obs=byt es 
bs=byt es 


Print a usage message on standard output and exit successfully. 

Print version information on standard output then exit successfully. 

Read from file instead of the standard input. 

Write to file instead of the standard output. Unless conv=nctrunc is given, truncate 
fileto the size specified by seek= (0 bytes if seek= isnot given). 

Read bytes bytes at a ti me. 

W rite by t es bytes atatime. 

Read and write bytes bytes at a time. Override ibs and obs. 
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Convert bytes bytes at a time. 

Skip bi ocks ibs-sized blocks at start of input. 

Skip bi ocks obs-sized blocks at start of output. 

Copy only bi ocks ibs-sized input blocks 
Convert the file as specified by the conversion arguments. 

Convert EBCDIC to ASCII. 

ConvertASCII to EBCDIC. 

Convert ASCI I to alternate EBCDIC. 

Pad newline-terminated records to size of cbs, replacing newlinewith trailing spaces. 
Replacetrailing spaces in cbs-sized block with newline. 

C hange uppercase characters to lowercase. 

C h an ge lowercase characters to uppercase. 

Swap every pair of input bytes. Unlike the UN IX dd, this works when an odd 
number of bytes are read. If theinputfilecontainsan odd number of bytes, the last 
byte is si mply copied (sincethere is nothing to swap itwith). 

C ontinueafter read errors 
D o not truncate the output file. 

Pad every input block to size of ibs with trailing nulls. 

GNU File Utilities 

depmod, modprobe— H andle loadable modules automatically 

SYNOPSIS 

depmod [-a] 

depmod modulel.o module2.o ... 

modprobe module.o [symbol=v a I ue ...] 
modprobe -t tag pattern 

modprobe -a -t tag pattern modprobe -1 [ -t tag ] pattern 
modprobe -r modul e 
modprobe -c 

DESCRIPTION 

These utilities are intended to make a Linux modular kernel manageable for all users, administrators, and distribution 
maintainers. 

depmod creates a makefile-1 ike dependency file, based on the symbols it finds i n the set of modules mentioned on the 
command line (or in a default place). This dependency file can later be used by modprobe to automatically load the relevant 
module(s). 

modprobe is used to load a set of modules- either a single module, a stack of dependent modules, or all modules that are 
marked with a specified tag. 

modprobe will automatically load all base modules needed in a module stack, as described by the dependency file modules, dep. 

If the loading of one of these modules fails, the whole current stack of modules will be unloaded (by rmmod) automatically. 

modprobe has two ways of loadi ng modules. Oneway (the probemode) will try to load amoduleout of a list (defined by 
pattern). It stops loading as soon as one module load successfully. This can be used to autoload one Ethernet driver out of a 
list, for example. The other way is to load all modules from a list. This can be used to load some modules at boot time. 


cbs=byt es 
skip=bl ocks 
seek=bl ocks 
count=bl ocks 

conv=conver s i on[,conversion...] 

Conversions: 

ascii 

ebcdic 

ibm 

block 

unblock 

lease 

ucase 

swab 

noerror 

notrunc 

sync 


depmod, modprobe 
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With the option -r, modprobe will automatically unload a stack of modules, similar to the way rmmod -r does. 

Option -l combined with option -t lists all available modules of a certain type. An enhanced mount command could use the 

command: 

modprobe -1 -t fs 

to get the list of all filesystem drivers available and on request load the proper one. So, the mount command could become 
more generic as well. (Thekerneid solves this without changing the mount utility.) 

Option -c will print all configuration (default + configuration file). 

Thenormal useof depmod isto include theline /sbin/depmod -a in oneof the rc-fiies in /etc/rc.d, so that the correct 
module dependencies will be available immediately after booting the system. 

Option -d puts depmod in debug mode. It outputs all commands it is issuing. 

Option -e outputs the list of unresolved symbol for each module, N ormally, depmod only outputs the list of unloadable 
modules. 

Option -v outputs the list of all processed modules. 

M odulesmay be located at different place in the filesystem, but there will always be some need to override this, especially for 
module developers. We expect some official standard will emerge, defined by theFSSTN D. Until that time, you might as 
well use this suggested directory structure. 

CONFIGURATION 

The behavior of depmod and modprobe can be adjusted by the (optional) configuration file /etc/cont .modules. 

The configuration file consists of a set of lines. All empty lines, and all text on a line after a#, will be ignored. Lines may be 
continued by ending the line with a \ . The remaining lines should all conform to oneof the following formats: 

keep 

parameter=value 

options module symbol=value ... 
alias module real_name 
pre-install module command ... 
install module command ... 
post-install module command ... 
pre-remove module command ... 
remove module command ... 
post-remove module command ... 

parameter=value options module symbol=value ... alias module real_name 

All values in the parameter lines will be processed by a shell, which means that shell tricks I ike wildcards and commands 
enclosed in backquotes can be used: 

path[misc]=/lib/modules/1.1.5?/misc 
path[net]=/lib/modules/'uname -r 1 /net 

Parameters may be repeated multiple times. 

These are the legal parameters: 

deptiie=DEPFiLE_PATH T his is the path to the dependency fi le that wi II be created by depmod and used by modprobe. 

path=soME_PATH T he path parameter specifies a directory to search for the modules. 

path [ tag] =some_path The path parameter can carry an optional tag. This tel Is us a little more about the purpose of the 
modules in this directory and allows some automated operations by modprobe. The tag is appended 
to the path keyword enclosed in square brackets. If the tag is missing, thetagmisc is assumed. 0 ne 
very useful tag is boot, which can be used to mark all modules that should be loaded at boot time. 

If the configuration file /etc/cont .modules is missing, or if any parameter is not overridden, the foil owing defaults are 
assumed: 
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ill 


depfile=/lib/modules/ 1 uname -r'/modules.dep 
path[boot] =/lib/modules/boot 

path[fs]=/lib/modules/'uname -r 1 /fs 
path[misc]=/lib/modules/'uname -r'/misc 
path[net]=/lib/modules/'uname -r'/net 
path[scsi]=/lib/modules/'uname -r'/scsi 

path[fs]=/lib/modules/default/fs 
path[misc]=/lib/modules/default/raise 
path[net]=/lib/modules/default/net 
path[scsi]=/lib/modules/default/scsi 

path [ fs]=/lib/modules/fs 
path[misc]=/lib/modules/misc 
path[net]=/lib/modules/net 
path[scsi]=/lib/modules/scsi 

All option lines specify the default options that are needed for a module, as in 
modprobe de620 bnc=1 

These options will be overridden by any options given on the modprobe command line. 

Thealiaslinescan beused to give alias names to modules. A linein /etc/conf .modules that looks like this: 
alias iso9660 isofs 

makes it possible to write modprobe iso9660, although there is no such module available. 

STRATEGY 

The idea is that modprobe will look first at the directory containing modules compiled for the current release of the kernel. If 
the module is not found there, modprobe will look in the directory containing modules for a default release. 

When you install a new Linux, the modules should be moved to a directory related to the release (and version) of the kernel 
you are installing. Then you should do asymlink from this directory to the default directory. 

Each time you compile a new kernel, the command make moduies_instaii will create a new directory, but won't change the 
default. 

When you get a module unrelated to the kernel distribution, you should place it in one of the version-independent 
directories under /iib/moduies. 

This is the default strategy, which can be overridden in /etc/conf .modules. 

EXAMPLES 

modprobe -t net 
modprobe -a -t boot 
modprobe slip.o 


modprobe -r slip.o 

FILES 

/etc/conf.modules 
/lib/modules/‘/modules.dep 
/lib/modules/* 


Load one of the modules that are stored in the directory tagged net. Each module istried until one 
succeeds. (Default: /lib/modules/net). 

All modules that are stored in the directory tagged boot will be loaded. (Default: /iib/moduies/ 
boot). 

This will attempt to load the module sihc.o if it was not previously loaded, si nee the si ip module 
needsthe functionality in thesihe module. This dependency will be described in thefile 
modules.dep that was created automatically by depmod. 

Will unload slip.o. I twill also unload sihc.o automatically, unless it is used by some other module 
as well (such asppp.o). 
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SEE ALSO 

lsmod(l), kerneld(8), ksyms(l), modules(2) 

REQUIRED UTILITIES 

insmod(l), nm(l) rmmod(l) 

NOTES 

The pattern supplied to modprobe will often be escaped to ensure that it is evaluated in the proper context. 

AUTHOR 

JacquesGelinas (jack^soiucorp.qc.ca), Bjorn Ekwall (bj 0 rn@biox.se) 

BUGS 

N aah... 

Linux, 14 May 1995 


df 

dt— Summarize free disk space 

SYNOPSIS 

df [-aikPv] [-tfstype] [-xfstype] [—all] [-inodes] [ — type=f s t y p e ] 
[ — exclude-type=fstype ] [-kilobytes] [ — portability] [-print-type] 
[—help] [—version] [filename...] 


DESCRIPTION 

This manual page documents the GN U version of df. df displays the amount of disk space avail able on the filesystem 
containing each filename argument. If no filename is given, the space available on all currently mounted filesystems is shown. 
D isk space is shown in IK blocks by default, unless the environment variable posixly_correct is set, in which case 512-byte 
blocks are used. 

If an argument is the absolute filename of a disk device node containing a mounted filesystem, df shows the space available 
on that filesystem rather than on the filesystem containing the device node (which is always the root filesystem). This version 
of df cannot show the space available on unmounted filesystems, because on most kinds of systems doing so requires very 
nonportable, intimate knowledge of filesystem structures. 


OPTIONS 

-a, —all 


-i, —Inodes 


-k, —kilobytes 
-P, —portability 


Include in the listing filesystems that haveO blocks, which are omitted by default. Such 
filesystems are typically special-purpose pseudo-filesystems, such as automounter entries. On 
some systems, filesystems of type ignore or auto are also omitted by default and included in the 
listing by this option. 

List inode usage information instead of block usage. An inode (short for "index node”) is a 
special kind of disk block that contains information about a file, such as its owner, permissions, 
timestamps, and location on thedisk. 

Print sizesin IK blocks instead of 512-byte blocks. T his overrides the environment variable 

POSIXLY_CORRECT. 

U se the posix output format. T his is like the default format except that the information about 
each filesystem is always printed on exactly one line; a mount device is never put on a line by 
itself. T his means that if the mount device name is more than 20 characters long (as for some 
network mounts), the columns are misaligned. 



-T, -print-type 
-t, — type=f s t y p e 


-x, —exclude-type=f stype 


-v 

— help 

— version 


Print a type string for each filesystem. Any such printed filesystem type name may be used as an 
argument to either of the -type= or -exciude-type= options 

Limit the listing to filesystems of type f s t y pe . M ultiple filesystem types can be shown by giving 
multiple-t options. By default, all filesystem types are listed. 

L imit the listi ng to fi lesystems not of type fstype. M ultiplefilesystem types can be eliminated by 
giving multiple-x options. By default, all filesystem types are listed. 

Ignored; for compatibility with System V versionsof df. 

Print a usage message on standard output and exit successfully. 

Print version information on standard output then exit successfully. 
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dig 

dig— Send domain name query packets to name servers 

SYNOPSIS 

dig [^server] domain [<quer y-1 y pe >] [<quer y-c I ass >] [+<quer y-opt i on >] [-<di g-opt i on>] 

[%comment ] 

DESCRIPTION 

dig (domain information groper) is a flexible command-line tool that can be used to gather information from the Domain 
N ame System servers, dig has two modes: simple interactive mode that makes a single query, and batch that executes a query 
for each in a list of several query lines. All query options are accessible from the command line. 

The usual simple use of dig takes the form: 

dig @server domain query-type query-class 

where 

server M ay be either a domain name or a dot-notation Internet address. If this optional field isomitted, 

dig will attempt to use the default name server for your machine. 


NOTE 


If a domain nameisspecified, this will be resolved using the domain name system resolver (bind). If your system does not 
support DNS, you may have to specify a dot-notation address. Alternatively, if there is a server at your disposal some¬ 
where, all that is required is that /etc/resoiv.conf be present and indicate where the default name servers reside, so that 
server itself can be resolved. Seeresoiver( 5 ) for information on /etc/resoiv.conf. 


WARNING 


Changing /etc/resoiv.conf will affect the standard resolver library and potentially several programs that use it.) As an 
option, theuser may set theenvi ronment variable localres to name a file which is to be used instead of /etc/resoiv.conf 
(localres is specific to thedig resolver and not referenced by thestandard resolver). If theLOCALREs variable is not set or 
thefileisnot readable then /etc/resoiv.conf will be used. 


domai n 


The domain name for which you are requesting information. See "Options" [-x] for a convenient 
way to specify inverse address query. 
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query-type The type of information (DNS query type) that you are requesti ng. If omitted, the default is a (t_a 

= address). T hefollowing types are recognized: 


Type 

Example 

Description 

a 

T_A 

N etwork address 

any 

T_ANY 

All/any information about specified domain 

mx 

T_MX 

Mail exchanger for the domain 

ns 

T_NS 

N ame servers 

soa 

T_SOA 

Zoneof authority record 

hinfo 

TJHINFO 

H ost information 

axf r 

T_AXFR 

Zone transfer (must ask an authoritative server) 

txt 

T_TXT 

Arbitrary number of strings 

(See RFC 1035 for the complete list.) 


query-class T he network class requested in the query. I f omitted, the default is in (c_in = internet). The 

followi ng cl asses are recogn i zed: 

in cjn Internet class domain 

any c_any All/any class information 

(See RFC 1035 for the complete list.) 


NOTE 


any can be used to specify a class and/or a type of query, dig will parse the first occurrence of any to mean query-type = 

T_ANY. 

To specify query-class = c_any you must either specify any twice, or set query-class using -c option. (See"Other Op¬ 
tions," next.) 


OTHER OPTIONS 

%ignored-comment % is used to include an argument that issimply not parsed. This may be useful if running dig in 
batch mode. Instead of resolving every ©server -domai n- name in a list of queries, you can avoid the 
overhead of doing so, and still have the domain name on the command line as a reference. 
Example: 

dig @128.9.0.32 %venera.isi.edu mx isi.edu 

-<dig opt i on > - is used to specify an option that affects the operation of dig. The following options are currently 

available (although not guaranteed to be useful): 

-x dot-not at i on - address C onvenient form to specify inverse address mapping. Instead of 

dig 32.0.9.128.in-addr.arpa 

one can simply use 
dig-x 128.9.0.32 

-f file Filefordig batch mode. T he file contains a list of query 

specifi cations (dig command lines) which are to be executed 
successively. Linesbeginningwith ;, #, or \n areignored. Other 
options may still appear on the command line, and will be in 
effect for each batch query. 

-t ti me Time in seconds between start of successive queries when running 

in batch mode. C an be used to keep two or more batch dig 
commands running roughly in sync. Default is zero. 
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-envsav 


-p port Port number. Query a name server listening to a nonstandard port 

number. Default is 53 . 

-p[pi ng- stri ng ] After query returns, execute a ping(8) command for response time 

comparison. This rather unelegantly makes a call to the shell. T he 
last three I ines of statistics is printed for the command: 
ping-sserver_name56 3 

If theoptional ping string ispresent, it replaces ping -sinthe 
shell command. 


-t quer y- 1 ype Specify type of query. M ay specify either an integer value to be 

included in thetype field or use the abbreviated mnemonic as 
discussed earlier (mx = t_mx). 

-c query- cl ass Specify class of query. M ay specify either an integer value to be 

included in the class field or use the abbreviated mnemonic as 
discussed earlier (in = c_in). 

This flag specifies that the dig environment (defaults, print options and so on), after all of the 
arguments are parsed, should be saved to a file to become the default environment. Useful if you do 
not like the standard set of defaults and do not desire to include a large number of options each 
timedig is used. The environment consists of resolver state variable flags, timeout, and retries as 
well as theflags detailing dig output (see below). If theshell environment variable localdef is set to 
the name of a file, this is where the default dig environment is saved. If not, thefile DiG.env is 
created in the current working directory. 


i N0TE I 

localdef is specific to the dig resolver, and will not affect operation of the standard resolver library. 


Each timedig is executed, it looks for ./DiG.env or the file specified by the shell environment 
variable localdef. If such file exists and is readable, then the environment is restored from thisfile 
before any arguments are parsed. 

-envset 

This flag only affects batch query runs. When -envset is specified on a line in a dig batch file, the 
dig environment after the arguments are parsed, becomes the default environment for the duration 
of the batch file, or until the next line which specifies -envset. 

-[no]stick 

This flag only affects batch query runs. It specifies that the dig environment (as read initially or set 
by -envset switch) isto be restored before each query (line) in a dig batch file. The default -nostick 
meansthatthedigenvironmentdoesnotstick, hence options specified on a single line in adig 
batch file will remain in effect for subsequent lines (that is, they are not restored to the sticky 
default). 

+<query opt i on> 

+ is used to specify an option to be changed in the query packet or to change dig output specifics. 

M any of these are the same parameters accepted by nsiookup(8). If an option requires a parameter, 
the form is as follows: 


ikeyword[=value] 

M ost keywords can be abbreviated. Parsing of the -i-options is very simplistic— a value must not be 
separated from its keyword by whitespace. The following keywords are currently available: 

K^word Abbreviation 

M eaning (Default) 

[no]debug (deb) 

Turn on/off debugging mode[deb] 

[no]d2 

T urn on/off extra debuggi ng mode [nod 2 ] 

[no]recurse (rec) 

U s^don't use recursive lookup [rec] 

retry=# (ret) 

Set number of retries to #[ 4 ] 


continues 
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Ke/word Abbre/iation 

M eaning (Default) 

time=#(ti) 

Set timeout length to #seconds [ 4 ] 

[no]ko 

Keep open option (implies vc) [noko] 

[no]vc 

Us^don't use virtual circuit [novo] 

[no]defname (def) 

Us^don't use default domain name[def] 

[no]search (sea) 

Use/don't use domain search list [sea] 

domain=NAME (do) 

Set default domain name to name 

[no]ignore (i) 

Ignor^don't ignoretrunc. errors [noi] 

[no]primary (pr) 

U se/don't use primary server [nopr] 

[no]aaonly(aa) 

Authoritative query only flag [noaa] 

[no]sort (sor) 

Sort resource records [nosor] 

[ no]cmd 

Echo parsed arguments [cmd] 

[no]stats (st) 

Print query statistics [st] 

[no]Headen (h) 

Print basic header [h] 

[no]headen(he) 

Print header flags [he] 

[no]ttlid (tt) 

Print TT Ls [tt] 

[no]cl 

Print class info [nocl] 

[ no]qr 

Print outgoing query [noqr] 

[no]reply (rep) 

Print reply [rep] 

[no ] ques (qu) 

Print question section [qu] 

[no]answer(an) 

Print answer section [an] 

[no]author(au) 

Print authoritative section [au] 

[ no]addit (ad) 

Print additional section [ad] 

pfdef 

Set to default print flags 

pfmin 

Set to minimal default print flags 

pfset=# 

Set print flags to # (# can be hex/octal/decimal) 

pfand=# 

Bitwise and printflagswith # 

pfor=# 

Bitwise or print flags with # 

The retry and time options affect the retransmission strategy used by resolver library when sending datagram queries. The 

algorithm is as follows: 


August 30, 1990 
for i = 0 to retry - 1 


for j = 1 to num_servers 


send_query 

wait((time * (2**i)) / num_servers) 
end 

end 


Note that dig always uses a value of i for num_servers. 

DETAILS 


dig once required a slightly modified version of the bind resolver (3) library, bind's resolver has (as of bind 4.9) been 
augmented to work properly with dig. Essentially, dig is a straightforward (albeit not pretty) effort of parsing arguments and 
setting appropriate parameters, dig uses resolver routines res_init(), res_mkquery(), res_send() as well as accessi ng res 

structure. 
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FILES 

/etc/resoiv.conf Initial domain nameand name server addresses 

ENVIRONMENT 

LOCALRES file to use in placeof /etc/resoiv.conf 
localdef default environment file 

AUTHOR 

Steve H otz (hotz@isi.edu) 

ACKNOWLEDGMENTS 

dig uses functions from nsiookup(8) authored by Andrew Cherenson. 

BUGS 

dig has a serious case of "creeping featurism," the result of considering several potential uses duri ng its development. It would 
probably benefit from a rigorous diet. Similarly, the print flags and granularity of the items they specify make evident their 
rather ad hoc genesis. 

dig does not consistently exit nicely (with appropriate status) when a problem occurs somewhere in the resolver (M ost of the 
common exit cases are handled.) T his isparticularly annoying when running in batch mode. If it exits abnormally (and is not 
caught), the entire batch aborts; when such an event is trapped, dig simply continues with the next query. 

SEE ALSO 

named®, resolver®, resolver(5), nslookup(8) 

30 August 1990 


dnsquery 

dnsquery - Q uery domain name servers using resolver 

SYNOPSIS 

dnsquery [-n nameserver ] [-t type] [-c class] [-r retry] [-p retry period] 

[-d] [-s] [-v] host 

DESCRIPTION 

The dnsquery program is a general interface to nameservers via bind resolver library calls. The program supports queries to the 
nameserver with an opcode of query. This program is intended to be a replacement or supplement to programs like nstest, 
nsquery, and nsiookup. All arguments except for host and ns are treated without case-sensitivity. 

OPTIONS 

-n The nameserver to be used in the query. N ameservers can appear as either Internet addresses of the form 

w. x. y. z or can appear as domain names, (default: as specified in /etc/resoiv.conf) 

-t The type of resource record of interest. T ypes include: 


A 

Address 

NS 

N ameserver 

CNAME 

Canonical name 

PTR 

Domain name pointer 

SOA 

Start of authority 
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WKS 

Well-known service 

HINFO 

H ost information 

MINFO 

M ail box information 

MX 

M ail exchange 

RP 

Responsible person 

MG 

M ail group member 

AFSDB 

DCE orAFS server 

ANY 

Wildcard 


NOTE 


Any case may be used (the default is any) 

-c Theclassof resource records of interest. C lasses include the following: 


IN 

Internet 

HS 

H esiod 

CHAOS 

Chaos 

ANY 

Wildcard 


NOTE 


Any case may be used (the default is in). 

-r The number of times to retry if thenameserver is not responding, (default: 4) 

-p Period to wait before timing out. (default: resjtimeout) options field, (default: any answer) 

-d T urn on debugging. ThissetstheREs_DEBUG bit of the resolver's options field, (default: no debugging) 

-s Use a stream rather than a packet. This uses a T CP stream connection with thenameserver rather than a 

U D P datagram. ThissetstheREs_usEvc bit of the resolver's optionsfield. (default: udp) 

-v Synonym for the s flag. 

host The name of the host (or domain) of interest. 

FILES 

/etc/resolv.conf 
<arpa/nameser.h> 

<resolv.h> 

SEE ALSO 

nslookup(8), nstest(l), nsquery(l), named(8), resolver(5) 

DIAGNOSTICS 

If the resolver fails to answer the query and debugging has not been turned on, dnsquery will simply print a message like this: 

Query failed (rc = 1) : Unknown host 

The value of the return code is supplied by h_errno. 


T o get the default ns and search lists. 
List of usable rr types and classes 
List of resolver flags 
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BUGS 

Queries of a class other than in can have interesting results si nee ordinarily a nameserver only has a list of root nameservers 
for class in resource records. 

Query uses a call to inet_addr() to determine if the argument for the -n option is a valid Internet address. U nfortunately, 
inet_addr() seemsto cause a segmentation fault with some (bad) addresses (for example, i .2.3. 4 .5). 

AUTHOR 

Bryan Beecher 

10 March 1990 


domainname 

domainname— Set or print domain of current host 

SYNOPSIS 

domainname [ name ] 

DESCRIPTION 

domainname prints the domai n name of the current host, from thegetdomainname( 3 ) library call. If an argument ispresentand 
the effective UID ise, domainname changes the name of the host, with thesetdomainname( 2 ) system call. T his is usually done at 
boot time in the /etc/rc. local script. 

FILES 

/etc/rc.local 

SEE ALSO 

getdomainname( 3 ), setdomainname( 2 ), uname(l), uname( 2 ) 

AUTHOR 

Lars Wirzenius by substituting in hostname.c 

Linux0.98, 26 December 1992 


dsplit 

dspiit— Split a largefile into pieces 

SYNOPSIS 

dsplit [ -size nnn ][i nputfi I e [ out putbase ]] 

DESCRIPTION 

dsplit splits binary files into smaller chunks so that they may be placed on floppy disks. 

OPTIONS 

-size nnn Specifies the size of each output file, in bytes. The default is 1457000, which is enough to will a 

1.44M B floppy disk. 

i nput _f i 1 e Specifies the name of the file to split up. A - indicates standard input. The default is standard 

input. 
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out put_base Specifies the name of the output fils to be written, dspiit will append 000 , 001 , ..., to the 

output_base. The default is dspiit. 


AUTHOR'S NOTES 

Submitted by: D avid Arnstein (amstein@netcom.com) 

Posting number: Volume40,1ssue 51 
Archive name: dspiit/partai 
Environment: M S-DOS, U N IX 

Here is a portable binary file splitting program. It reads a binary file and splits it into pieces. I use this program to put large 
binary files on floppy disks. For this reason, the default size of the output files is 1,457,000 bytes, which just about fills up a 
1.44M B floppy disk. 

Unlike other binary split programs I have seen, dspiit does not maiioc a huge block of memory, dspiit is suitablefor use 
under MS-DOS and other primitive operating systems. 

(Theprogram camefrom gatekeeper.dec.com: /pub/usenet/comp.sources.misc/volume 40 /dsplit). 

Linux 1.1, 5July 1994 


du 

du— Summarize disk usage 

SYNOPSIS 

du [-abcklsxDLS] [—all] [—total] [-count-links] [—summarize] [—bytes] 
[ — kilobytes] [-one-file-system] [ — separate-dirs] [—dereference] 

[ —dereference-args] [—help] [--version] [filename...] 


DESCRIPTION 

This manual page documents the GN U version of du. du displays the amount of disk space used by each argument and for 
each subdirectory of directory arguments. The space is measured in IK blocks by default, unless the environment variable 
posixly_correct i sset, in which case 512-byte blocks are used. 


OPTIONS 

-a, —all 
-b, -bytes 
-c, —total 

-k, —kilobytes 
-1, -count-links 
-s, —summarize 
-x, -one-file-system 

-D, —dereference-args 


-L, —dereference 

-S, —separate-dirs 

— help 

— version 


D isplay counts for all files, not just directories. 

Print sizes in bytes. 

Write a grand total of all of thearguments after all arguments have been processed. This can 
be used to find out the disk usage of a directory, with some files excluded. 

Print sizes in kilobytes. T his overrides the environment variable posixly_correct. 

Count the size of all files, a/en if they have appeared already in another hard link. 

D isplay only a total for each argument. 

Skip directories that are on different filesystems from the one that the argument being 
processed is on. 

D ereference symbolic I inks that are command-line arguments D oes not affect other 
symbolic links. T his is helpful for findi ng out the disk usage of directories like /usr/tmp 
where they are symbolic links 

D ereference symbolic links (show the disk space used by the file or di rectory that the link 
points to instead of the space used bythelink). 

Count the size of each directory separately, not including the sizes of subdirectories. 

Print a usage message on standard output and exit successfully. 

Print version information on standard output, then exit successfully. 
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BUGS 

0 n BSD systems, du reports sizes that are half the correct values for files that are N FS-mounted from H P-U X systems. 0 n 
HP-UX systems, it reports sizes that are twice the correct values for files that are N FS-mounted from BSD systems. This is 
due to aflaw in H P-UX; it also affects the H P-U X du program. 

GNU File Utilities 


editres 

editres— A dynamic resource editor for X T oolkit applications 

SYNTAX 

editres [ -t ool ki t opt i on ... ] 

OPTIONS 

editres accepts all of the standard X Toolkit command-line options (seex(l)). T he order of the command-li ne options is not 
important. 

DESCRIPTION 

editres is a tool that allows users and application developers to view thefull widget hierarchy of anyX Toolkit application 
that speaks the editres protocol. In addition, editres will help the user construct resource specifications, allow the user to 
apply the resource to the application and view the results dynamically. 0 nee the user is happy with a resource specification, 
editres will append the resource string to theuser'sX Resources file. 

USING editres 

editres provides a window consisting of the foil owing four areas: 

M enu Bar A set of pop-up menus that allow you full access to editres's features. 

Panner Thepanner provides a more intuiti ve way to scroll the application tree display. 

M essageArea D isplays information to the user about the action that editres expects. 

Application WidgetT ree This area is used to display the selected application's widget tree. 

To begin an editres session, select the Get Widget T ree menu item from the Command menu. This will change the pointer 
cursor to crosshair. You should now select the application you wish look at by clicking on any of its windows. If this 
application understands the editres protocol, editres will display theapplication'swidgettreein its tree window. If the 
application does not understand the editres protocol, editres will inform you of this fact in the message area after a few 
seconds delay. 

After you have a widget tree you may select any of the other menu options. The effect of each of these is described in 
"Commands,'' next. 

COMMANDS 

Get WidgetT ree 
Refresh C urrent W idget T ree 


Allows the user to click on any application that speaks the editres protocol and receive its 
widget tree. 

editres only knows about the widgets that exist at the present time M any applications 
create and destroy widgets on the fly. Selecting this menu item will cause edit res to ask the 
application to resend its widget tree, thus updating its information to the new state of the 
application. 

For example, xman only creates the widgets for its topbox when it starts up. N one of the 
widgets for the manual page window are created until the user actually clicks on theM anual 
Page button. Ifyou retrieved xman'swidget tree before the manual page is active, you may 
wish to refresh the widget tree after the manual page has been displayed. This will allow you 
to also edit the manual page's resources. 
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Dump Widget T reeto a File 


Show Resource Box 


Set Resource 


Quit 


W hen documenting applications it is often useful to be able to dump the entire application 
widget tree to an ASCI I file. Thisfile can then beincluded inthe manual page. W hen this 
menu item is selected, a pop-up dialog is activated. Type the name of the file in this dialog, 
and either select 0 kay, or type a carriage return, editres will dump the widget tree to this 
file. T o cancel the file dialog, select the Cancel button. 

This command will pop up a resource box for the current application. This resource box 
(described in detail later in this section) will allow the user to see exactly which resources 
can be set for the widget that is currently selected inthe widget tree display. Only one 
widget may be currently selected; if greater or fewer are selected, editres will refuse to pop 
up the resource box and put an error message in the M essage Area. 

Thiscommand will pop up a simple dialog box for setting an arbitrary resourceon all 
selected widgets. You must type in the resource name, as well as the value. You can use the 
T ab key to switch between the resource namefield and the resource value field. 

Exits editres. 


TREECOMMANDS 


TheT reemenu contains sa/eral commands that enable operationsto be performed on the widget tree. 


Select Widget in Client 


Select All, Unselect All, 
Invert All 
Select Children, 

Select Parents 
Select Descendants, 
Select Ancestors 
Show Widget Names, 
Show Class Names, 
Show Widget Windows 


Flash Active Widgets 


Thismenu item allows you to select any widget in theapplication; editres will then 
highlight the corresponding element the widget tree display. After thismenu item is 
selected, the pointer cursor will again turn to a crosshair, and you must click any pointer 
button in the widget you wish to have displayed. Since some widgets are fully obscured by 
their children, itisnot possi ble to get to every widget thisway, butthismechanism does 
give very useful feedback between the elements in the widget tree and those in the actual 
application. 

These functions allow theuserto select, unselect, or invert all widgets in the widget tree 

T hese functions select the immediate parent or children of each of the currently selected 
widgets. 

These functions select all parentsor children of each of the currently selected widgets. This 
is a recursive search. 

W hen the tree widget is initially displayed, the labels of each widget in the tree correspond 
to the widget names. These functions will cause the label of all widgets in the tree to be 
changed to show the class name, IDs, or window associated with each widget in the 
application. Thewidget IDs, and windows are shown as hex numbers. 

In addition, there are keyboard accelerators for each of theT ree operations. If theinput 
focus is over an individual widget in thetree, then that operation will only affect that 
widget. If the input focus is in theT ree background, it will have exactly the same effect as 
the corresponding menu item. 

The translation entries shown may be applied to any widget in theapplication. If that 
widget isachild of theT ree widget, then itwill only affect that widget; otherwise it will 
have the same effect as the commands in theT ree menu. 

Thiscommand isthe inverse of the Select Widget in Client command; itwill show the user 
each widget that is currently selected in the widget tree by flashing the correspond! ng widget 
in theapplication numFiashes (three by default) times in thefiash-coior. 


Key 

Option 

T randation Entry 

space 

Unselect 

Select(nothing) 

w 

Select 

Select(widget) 

s 

Select 

Select(all) 

i 

Invert 

Select( invert) 
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Ke/ 

Option 

Translation Entry 

c 

Select 

Children Select(children) 

d 

Select Descendants 

Sel ect( d escen dan ts) 

P 

Select Parent 

Selectf parent) 

a 

Select Ancestors 

Select! ancestors) 

N 

Show Widget Names 

Relabel (name) 

C 

Show C lass N ames 

Relabel (cl ass) 

1 

Show Widget IDs 

Relabel(id) 

W 

Show Widget Windows 

Relabel(window) 

T 

T oggle W idget/C lass N ame 

Relabel(toggle) 


Clicking button 1 on a widget adds it to the set of selected widgets. Clicking button 2 on a widget deselects all other widgets 
and then selects just that widget. Clicking button 3 on a widget toggles its label between the widget's instance name the 
widget's cl ass name. 


USING THE RESOURCE BOX 


The resource box contains five different areas. Each of the areas, as the/appear on the screen from top to bottom, are 
discussed in the following list: 


The Resource Line 

The Widget Names and Classes 


N ormal and Constraint Resources 


ResourceValue 


This area at the top of the resource box shows the current resource name exactly as it 
would appear if you were to save it to a file or apply it. 

T his area enables you to select exactly which widgets this resource will apply to. T he 
area contains four lines; the first contains the name of the selected widget and ail its 
ancestors, and the more restrictive dot (.) separator. The second line contains less 
specific class names of each widget, as well as the less restrictive star (*) separator. 

The third line contains a set of special buttons cal led Any W idget that will generalize 
this level to match any widget. The last line contains a set of special buttons called 
Any Widget Chain that will turn the single level into something that matches zero or 
more levels. 

Theinitial state of this area isthemost restrictive, using the resource names and the 
dot separator. By selecting the other buttonsin thisarea, you can ease the restrictions 
to allow more and more widgets to match the specification. The extreme case is to 
select all theAny Widget Chain buttons, which will match every widget in the 
application. As you select different buttons, the tree display will update to show you 
exactly which widgets will be affected by the current resource specification. 

T he next area allows you to select the name of the normal or constraint resources 
you wish to set. Some widgets may not have constraint resources, so that area will 
not appear. 

This next area allows you to enter the resource value. This value should be entered 
exactly as you would type a line into your resource file. Thus, it should contain no 
unescaped newlines. There are a few special character sequences for this file: 

\n- Thiswill be replaced with a newline. 

\###- Where# is any octal digit. Thiswill be replaced with a single 

byte that containsthis sequence interpreted as an octal 
number. For example, a value containing a null byte can be 
stored by specifying \me. 

\<new-iine>- T his will compressto nothing. 

\\- Thiswill compressto a single backslash. 
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Command Area This area contains several command buttons, described in thefollowing list: 

TheSet Save File button allows the user to modify filethat the resources will be 
saved to. This button will bring up a dialog box that will ask you for a filename; 
after the filename has been entered, either hit carriage-return or click on the 
Okay button. T o pop down the dialog box without changing the save file, click 
the Cancel button. 

The Save button will append the resource line already described to the end of the 
current save file. If no save file has been set, the Set Save File dialog box will be 
popped up to prompttheuserforafilename. 

T he Apply button attempts to perform axtsetvaiues call on all widgets that 
match the resource line descri bed earlier. The value specified isapplied directly 
to all matching widgets. This behavior is an attempt to give a dynamic feel to the 
resource editor. Since this feature allows users to put an application in states it 
may not be willing to handle, a hook has been provided to allow specific 
applications to block these setvaiues requests. (See "B locking editres Requests," 
following). 

U nfortunately, due to design constraints imposed on the widgets by theX 
Toolkit and the Resource M anager, trying to coerce an inherently static system 
into dynamic behavior can cause strange results T here is no guarantee that the 
results of an apply will be the same as what will happen when you save the value 
and restart the application. This functionality is provided to try to give you a 
rough feel forwhatyour changes will accomplish, and the results obtained 
should be considered suspect at best. H avingsaid that, this isone of the neatest 
features of editres, and I strongly suggest that you play with it, and see what it 
can do. 

The Save and Apply button combines the Save and Apply actions described 
earlier into one button. 

ThePopdown Resource Box button will remove the resource box from the 
display. 

BLOCKING editres REQUESTS 

The editres protocol has been built into the Athena W idget set. This allows all applications that are linked againstxawto be 
able to speak to the resource editor. Although this provides great flexibility, and is a useful tool, it can quite easily be abused. 
It istherefore possible for any xaw application to specify a value for the editresBiock resource to keep editres from divulging 
information about its internals, or to disable the setvaiues part of the protocol. 

editresBiock (Class Editresbiock) specifies which type of blocking this application wishes to impose on the editres protocol. 
The accepted values are as follows: 
ail Block all requests. 

setvaiues Block all setvaiues requests. As this isthe only editres request that actually modifiestheapplication, this 

isin effect stating that theapplication isread-only. 
none Allow all editres requests. 

Remember that these resources are set on any xaw application, not editres. They allow individual applications to keep all or 
some of the requests editres makes from ever succeeding. Of course, editres is also an xaw application, so it may also be 
viewed and modified by editres (rather recursive, I know); these commandscan be blocked by settingtheeditresBiock 
resource on editres itself. 

RESOURCES 

For editres, the available application resources are as follows: 

numFiashes (C lassNumFiashes) specifies the number of times the widgets in theapplication will be flashed when the Show 
Active Widgets command in invoked. 
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fiashTime (C lass FiashTime) specifies the mount of time between the flashes described in the preceding entry, 
tiashcoior (C lass f lashcoior) specifies the color used to flash application widgets. A bright color should be used that will 
immediately draw your attention to the area being flashed, such as red or yellow. 

saveResourcesFiie (C lass saveResourcesFiie) is the file the resource line will be append to when the Save button activated in 
the resource box. 

WIDGETS 

In order to specify resources, it is useful to know the hierarchy of thewidgets that compose editres. In the following 
notation, indentation indicates hierarchical structure. The widget class name is given first, followed by the widget instance 
name. 

Editres editres 

Paned paned 
Box box 

MenuButton commands 
SimpleMenu menu 
SmeBSB sendTree 
SmeBSB refreshTree 
SmeBSB dumpTreeToFile 
SmeLine line SmeBSB getResourceList 
SmeLine line 
SmeBSB quit 

MenuButton treeCommands 
SimpleMenuumenu 
SmeBSB showClientWidget 
SmeBSB selectAll 
SmeBSB unselectAll 
SmeBSB invertAll 
SmeLine line 
SmeBSB selectChildren 
SmeBSB selectParent 
SmeBSB selectDescendants 
SmeBSB selectAncestors 
SmeLine line 
SmeBSB showWidgetNames 
SmeBSB showClassNames 
SmeBSB showWidgetIDs 
SmeBSB showWidgetWindows 
SmeLine line 

SmeBSB flashActiveWidgets 
Paned hPane 

Panner panner 
Label userMessage 
Grip grip 
Porthole porthole 
Tree tree 

Toggle <name of widget in application> 


TransientShell resourceBox 

Paned pane 

Label resourceLabel 

Form namesAndClasses 

Toggle dot 

Toggle star 

Toggle any 

Toggle name 
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Toggle class 


Label namesLabel 
List namesList 
Label constraintLabel 
List constraintList 
Form valueForm 
Label valueLabel 
Text valueText 
Box commandBox 
Command setFile 
Command save 
Command apply 
Command saveAndApply 
Command cancel 
Grip grip 

Grip grip 


ENVIRONMENT 

display T o get the default host and display number 

xenvironment T o get the name of a resource file that overrides the global resources stored in the resource_manager 
property. 

FILES 

<xRoot>/iib/xi i /app-defauits/Editres specifies required resources. 

SEE ALSO 

x(l), xrdb(l), Athena Widget Set 

RESTRICTIONS 

This is a prototype There are lots of nifty features I would love to add, but I hope this will give you some ideas about what a 
resource editor can do. 

AUTHOR 

C hris D. Peterson (formerly M IT X C onsortium) 

X Version 11 Release6 

elvis, ex, vi, view, input 

elvis, ex, vi, view, input —The editor 

SYNOPSIS 

elvis [fl ags ][+cmd][fi I es ...] 

DESCRIPTION 

elvis is a text editor that emulates vi/ex. 

On systemswhich pass the program name as an argument, such asU NIX and M inix, you may also install eivis under the 
names ex, vi, view, and input. These extra names would normally be I inks to eivis; see the in shell command. 




eluis, ex, vi, niew, input 

When eivis is invoked asvi, it behaves exactly as though it was invoked aseivis. H owever, if you invoke eivis as view, then 
the readonly option is set as though you had given it the -r flag. If you invoke eivis as ex, then eivis will start up in the 
colon command mode instead of the visual command mode, as though you had given it the -e flag. If you invoke eivis as 
input or edit, then eivis will start up in input mode, as though the -i flag was given. 

OPTIONS 


-r 

T o the real vi, this flag means that a previous edit should be recovered, eivis, though, has a 
separate program, called eivrec(l), for recovering files. W hen you invoke eivis with -r, eivis will 
tell you to run eivrec. 

-R 

This sets the readonly option, so you won't accidentally overwrite a file. 

•s 

This sets the safer option, which disables many potentially harmful commands. It has not been 
rigorously proven to be absolutely secure, however. 

-t tag 

This causes eivis to start editing at the given tag. 

-m [file] 

eivis will search through file for something that looks like an error message from a compiler. It 
will then begin editing the source file that caused the error, with the cursor sitting on the line where 
the error was detected. If you don't explicitly nameafile, then erriist isassumed. 

-e 

eivis will startup in colon command mode. 

-V 

eivis will start up in visual command mode. 

-i 

eivis will start up in input mode. 

-w winsize 

Sets the window option's value to winsize. 

+command OT -c command 

If you usethe+command parameter, then after the first file is loaded, command isexecuted as an ex 
command. A typical examplewould beeivis + 23 / too, which would cause eivis to start editing 
too and then move directly to line 237. The -c command variant was added for UNIX SysV 
compatibility. 

FILES 


/tmp/elv* 

D uring editing, eivis stores text in a temporary file For U NIX, this file will usually be stored in 
the /tmp directory, and the first three characters will beeiv. For other systems, the temporary files 
may be stored someplace else; see the version-specific section of the documentation. 

tags 

T his is the database used by the :tags command and the -t option. It is usually created by the 
ctags(l) program. 

.exrc Or eivis.re 

On U N IX-like systems, a file called .exrc in your home directory isexecuted as a series of ex 
commands. A file by the same name may be executed in the current directory, too. On non-U NIX 
systems .exrc is usually an invalid filename; there, the initialization fileiscalled eivis.rc instead. 

ENVIRONMENT 


TERM 

This is the name of your terminal'sentry in thetermcap or terminfo database. The list of legal 
values varies from one system to another. 

TERMCAP 

Optional. If your system usestermcap, and the termcap variable is unset, then eivis will read your 
terminal's definition from /etc/termcap. If termcap is set to the full pathname of a file (starting with 
a /) then eivis will look in the named file instead of /etc/termcap. If termcap is set to a value which 
doesn't start with a /.then its value is assumed to be the full termcap entry for your terminal. 

TERMINFO 

Optional. If your system uses terminfo, and the terminfo variable is unset, then eivis will read your 
terminal's definition from the database in the/usr/iib/terminfo database. If terminfo is set, then its 
value is used as the database name to use instead of /usr/iib/terminfo. 

LINES, COLUMNS 

Optional. These variables, if set, will override the screen size values given in thetermcap/terminfo 
for your terminal. On windowing systems such asX, eivis has other ways of determining the 
screen size, so you should probably leave these variables unset. 

EXINIT 

Optional. This variable can hold ex commands which will be executed instead of the .exrc file in 
your home directory. 
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shell Optional. The shell variable sets the default value for the shell option, which determines which 

shell program isused to perform wildcard expansion in filenames, and also which isused to execute 
fi Iters or external programs. The default value on U NIX systems is /bin/sh. 

N ote: U nder M S-DOS, this variable is called comspec instead of shell, 
home This variable should beset to the name of your home directory, eivis looks for its initialization file 

there; if home is unset, then the initialization file will not be executed. 
tagpath Optional. Thisvariableisused by the ret program, which isinvoked by theshift-K, control-], 

and : tag commands. See ref for more information. 

tmp, temp These optional environment variables are only used in non-U NIX versions of eivis. They allow 

you to supply a directory name to be used for storing temporary files. 

SEE ALSO 

ctags(l), ref(l), elvprsv(l), elvrec(l) 

Elvis-A Cloneof Vi/Ex, the complete eivis documentation. 

BUGS 

There is no Lisp support. Certain other features are missing, too. 

Auto-indent mode is not quite compatible with the real vi. Among other things, o'd and "d don't do what you might 
expect. 

Long lines are displayed differently. The real vi wraps long lines onto multiple rows of the screen, but eivis scrolls si deways. 

AUTHOR 

Steve Kirkendall (kirkenda§cs.pdx.edu) 

M any other people have worked to port eivis to various operating systems. T o see who deserves credit, run the: version 
command from within eivis, or look in the system-specific section of the complete documentation. 

elvprsv 

eivprsv — Preserve the modified version of a file after a crash 

SYNOPSIS 

elvprsv ["-why eivis died"] /tmp/f i I ename... 
elvprsv -R /tmp/f i I ename... 

DESCRIPTION 

elvprsv preserves your edited text after eivis dies. The text can be recovered later, via the elvprsv program. 

For U N IX-like systems, you should never need to run this program from the command line. It is run automatically when 
eivis is about to die, and it should be run (via /etc/rc) when the computer is booted. THAT'S ALL! 

For non-U NIX systems such asM S-DOS or VM S, you can either use elvprsv the same way asunder UN IX systems (by 
running it from your autoexec.bat file), or you can run it separately with the -r flag to recover the files in one step. 

If you're editing a file when eivis dies (due to a bug, system crash, power failure, and so on), then elvprsv will preserve the 
most recent version of your text. The preserved text is stored in a special directory; it does not overwrite your text file 
automatically. (If the preservation directory hasn't been set up correctly, then elvprsv will simply send you a mail message 
describing how to manually run elvprsv.) 

elvprsv will send mail to any user whose work it preserves, if your operating system normally supports mail. 
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FILES 

/tmp/elv* 

/usr/preserve/p* 

/usr/preserve/Index 


T he temporary file that eivis was using when it died. 

T he text that is preserved by eivprsv. 

A text file which lists the names of all preserved files, and the names of the /usr/preserve/p* files 
that contain their preserved text. 


BUGS 

Due to the permissions on the/usr/preserve directory, on U N IX systems eivprsv must be run as superuser. This is 
accomplished by making the eivprsv executable be owned by root and turning on its "set user id” bit. 

If you're editing a nameless buffer when eivis dies, then eivprsv will pretend that the file was named too. 

AUTHOR 

Steve Kirkendall (kirkenda@cs.pdx.edu) 

elvrec 

elvrec— Recover the modified version of a file after a crash 

SYNOPSIS 

elvrec [preservedf i I e [newfile]] 

DESCRIPTION 

If you're editing a file when eivis dies, the system crashes, or power fails, the most recent version of your text will be 
preserved. The preserved text is stored in a special directory; it does not overwrite your text file automatically. 

The elvrec program locates the preserved version of a given file and writes it over the top of your text file—or to a newfile, 
if you prefer. The recovered file will have nearly all of your changes. 

T o see a list of all recoverable files, run elvrec with no arguments. 


NOTE 


If you haven't set up a directory for file preservation, you’ll have to manually run the eivprsv program instead of elvrec. 


FILES 

/usr/preserve/p* 

/usr/preserve/Index 


The text that was preserved when eivis died. 

A text filethat lists the names of all preserved files, and the names of the /usr/preserve/p* files that 
contain their preserved text. 


BUGS 

elvrec is very picky about filenames. You must tell it to recover the file using exactly the same path name as when you were 
editing it. The simplest way to do this is to go into the same directory that you were editing, and invoke elvrec with the 
same filename as eivis. If that doesn't work, then try running elvrec with no arguments, to see exactly which pathname it is 
using for the desired file. 

Due to the permissions on the /usr/preserve directory, on U N IX systems elvrec must be run as superuser. This is 
accomplished by making the elvrec executable be owned by root and setting its "set user id” bit. 

If you're editing a nameless buffer when eivis dies, then elvrec will pretend that the file was named too. 
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AUTHOR 


Steve Kirkendall (kinkenda@cs.pdx.edu) 


emacs 

emacs —GNU project emacs 

SYNOPSIS 

emacs [ command-line switches ] [files ... ] 

DESCRIPTION 

GNU emacs is a version of emacs, written by the author of the original (PD P-10) emacs, Richard Stallman. 

The primary documentation of GN U emacs is in the GNU EmacsM anual, which you can read online using info, a 
subsystem of emacs. Please look therefor complete and up-to-date documentation. This man pageisupdated only when 
someone volunteers to do so; the emacs maintained' priority goal is to minimize the amount of time this man page takes 
away from other more useful projects. 

The user functionality of GNU emacs encompasses everything other emacs editors do, and itiseasily extensible since its 
editing commands are written in Lisp. 

emacs has an extensive interactive help facility, but the facility assumes that you know how to manipulate emacs windows and 
buffers. Ctrl+h (backspace or Ctrl +h) enters the H elp facility. H el p T utorial (Ctrl+h t) requests an interactive tutorial that 
can teach beginners the fundamentals of emacs in a few minutes. H elp Apropos (Ctrl+h a) helps you find a command given 
its functionality, H elp Character (Ctrl+h c) describes a given character's effect, and H elp Function (Ctrl+h f) describes a 
given Lisp function specified by name. 

emacs'sUndo can undo several steps of modification to your buffers, so it is easy to recover from editing mistakes. 

GNU emacs'srnany special packages handle mail reading (RMaii) and sending (Mail), outline editing (outline), compiling 
(compile), running subshells within emacs windows(sheii), running a Lisp read-eval-print loop (Lisp-interaction-Mode), and 
automated psychotherapy (Doctor). 

There is an extensive reference manual, but users of other emacses should have little trouble adapting s/en without a copy. 
Users new to emacs will be able to use basic features fairly rapidly by studying the tutorial and using the self-documentation 
features. 

OPTIONS 

T he following options are of general interest: 
file Edit f i I e. 

+n umber Go to the line specified by number (do not insert a space between the + sign and the number). 

-q Do not load an init file 

-u user Load user's init file. 

-t file Use specified file as the terminal instead of using stdin/stdout. This must be the first argument specified 

in the command line. 

T he following options are Lisp-oriented (these options are processed in the order encountered): 

-t function Execute the L isp function f u nc t i on. 

-l file Load the Lisp code in the fi lef i e. 

T he following options are useful when running emacs asabatch editor: 

-batch Edit in batch mode. The editor will send messages to stdout. This option must bethefi rst in the 

argument list. You must use -1 and -t optionsto specify files to execute and functions to call. 

Exit emacs while in batch mode. 


-kill 
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USING emacs with x 


emacs has been tailored to work well with theX Window System. If you run emacs from under X windows, it will create its 
own X window to display in. You will probably want to start the editor as a background process so that you can continue 
using your original window. 


emacs can be started with the following X switches: 


-rn name 

-name name 

-r 

-i 

-font font, -fn f ont 


-b pixels 
-ib pi xel s 
-geometry geomet r y 

-fg color 


Specifies the program namewhich should beused when looking up defaults in the 
user's X resources. This must be the first option specified in the command line. 
Specifies the name that should be assigned to the emacs window. 

D isplay the emacs window in reverse video. 

Use the "kitchen sink” bitmap icon when iconifying theemacs window. 

Set the emacs wi ndow's font to that specified by font. You will find the various X 
fonts in the/usr/iib/xi i /fonts directory. N otethat emacs will only accept fixed 
width fonts. Under theXll Release 4 font-naming conventions, anyfontwith the 
value m or c in the eleventh field of the font name is a fixed width font. Furthermore, 
fonts whose name are of the form widthxheight are generally fixed width, as is the 
font fixed. Seexisfonts(l) for more information. 

When you specify a font, be sure to put a space between the switch and the font 
name 

Set theemacs window's border width to the number of pixels specified by pixels. 
Defaults to one pixel on each side of the window. 

Set the window's internal border width to the number of pixels specified by pi xel s. 
Defaults to one pixel of padding on each side of the window. 

Set theemacs wi ndow's width, height, and position as specified. The geometry 
specification isin thestandard uformat; seex(l) for more information. The width 
and height are specified in characters; the default is 80 by 24. 

On color displays, sets the color of thetext. Seethefile/usr/iib/xn/rgb.txt fora 
list of valid color names. 


-bg color 
-bd color 
-cr color 
-ms color 

-d di s pi ay name, -display display name 


-nw 


On color displays, sets the color of the window's background. 

On color displays, sets the color of the window's border. 

0 n color displays, sets the color of the window's text cursor. 

0 n color displays, sets the color of the window's mouse cursor. 

Create the emacs window on the display specified bydi spi ayname. M ust be the first 
option specified in the command line. 

T el Is emacs not to use its special interface to x. If you use this switch when invoking 
emacs from an xterm(l) window, display is done in that window. This must be the 
first option specified in the command line. 


You can set x default values for your emacs windows in your xresources file; seexrdb(l). Use the following format: 
emacs.keywor d: v a I ue 


wherevai ue specifies the default value of keyword, emacs lets you set default values for the following keywords: 


font (class Font) 

reverseVideo (class ReverseVideo) 
bitmaplcon (class Bitmaplcon) 
borderWidth (class BorderWidth) 
intennalBorder (class BorderWidth) 
foreground (class Foreground) 
background (class Background) 
borderColor (class BorderColor) 


Sets the window's text font. 

If reversevideo's value isset to on, thewindow will bedisplayed in reversevideo. 
If bitmapl con's value is set to on, thewindow will iconify into the "kitchen sink.” 
Sets the window's border width in pixels. 

Setsthewindow'sinternal borderwidth in pixels. 

For color displays, sets the window's text color. 

For color displays, sets the window's background color. 

For color displays, sets the color of the window's border. 
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cursorcoior (class Foreground) For color displays, sets the color of the window's text cursor. 

pointercoior (class Foreground) For color displays, sets the color of the window's mouse cursor. 

geometry (class Geometry) Sets the geometry Of the emacs window. 

title (class Title) Sets the title of the emacs window. 

iconName (class Title) Sets the icon name for the emacs window icon. 

If you try to set color values while using a black-and-white display, the window's characteristics will default as follows: The 
foreground color will beset to black, the background color will beset to white, the border color will be set to gray, and the 
text and mouse cursors will be set to black. 

USING THE MOUSE 

T he following lists the mouse button bindings for the emacs window underXll. 


M ouse Button 

Function 

left 

Setpoint. 

middle 

Paste text. 

right 

Cut text into X cut buffer. 

Shi ft-middle 

CuttextintoX cut buffer. 

Shift-Fright 

Paste text. 

Ctrl-middle 

Cut text into X cut buffer and kill it. 

Ctrl-Fright 

Select thiswindow, then split it into two windows. Sameastyping Ctrl+x 2. 

Ctrl+Shift-Heft 

X buffer menu; hold the buttons and keys down, wait for menu to appear, select buffer, and 
release. Move mouse out of menu and release to cancel. 

Ctrl+Shift-middle 

X help menu; pop up index card menu for emacs help. 

C trl+Shift+right 

Select window with mouse, and delete all other windows. Sameas typing Ctrl+x 1. 


MANUALS 

You can order printed copies of theGA/ L/ EmacsM anual from the Free Software Foundation, which develops GN U 
software. Seethefile orders for ordering information. 

Your local emacs maintainer might also have copies available. Aswith all software and publicationsfrom FSF, everyoneis 
permitted to make and distribute copies of the emacs manual. The T eX source to the manual is also included in the emacs 
source distri bution. 

FILES 

/usr/local/info 


/usr/local/lib/emacs/$VERSION/src 
/usr/local/lib/emacs/$VERSION/lisp 

/usr/local/lib/emacs/$VERSION/etc 
/usr/local/lib/emacs/$VERSION/etc/DOC.* 


Files for the info documentation browser (a subsystem of emacs) to 
refer to. Currently not much of U NIX is documented here, but the 
complete text of the emacs reference manual isincluded in a 
convenient tree structured form. 

C sourcefiles and object files. 

Lisp source files and compiled files that define most editing com¬ 
mands. Some are preloaded; others are autoloaded from this directory 
when used. 

Various programs that are used with GNU emacs, and some files of 
information. 

Containsthe documentation strings for the Lisp primitives and 
preloaded Lisp functions of GN U emacs. They are stored hereto 
reduce the size of emacs proper. 
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/usr/local/lib/emacs/$VERSION/etc/DIFF 
/usr/local/lib/emacs/$VERSION/etc/CCADIFF 
/usr/local/lib/emacs/$VERSION/etc/GOSDIFF 
/usr/local/lib/emacs/$VERSION/etc/SERVICE 


/usr/local/lib/emacs/lock 

/usr/local/lib/emacs/$VERSION/$ARCHITECTURE/cpp 


/usr/lib/X 11 /rgb.txt 


Discusses GNU emacs versus T wenex emacs. 

Discusses GNU emacs versus CCA emacs. 

Discusses GNU emacs versus Gosling emacs. 

Lists people offering various services to assist users of GN U emacs, 
including education, troubleshooting, porting, and customization. 
These files also have information useful to anyone wanting to write 
programs in the emacs Lisp extension language, which has not yet 
been fully documented. 

H olds lock files that are madefor all files being modified in emacs, to 
prevent simultaneous modification of onefilebytwo users. 

TheGN U cpp, needed for building emacs on certain versionsof 
UNIX where the standard cpp cannot handle long names for macros. 
List of valid x color names. 


BUGS 

T here is a mailing list, bug-gnu-emacs@prep.ai.mit.edu On the I nternet (ucbvax! prep .ai.mit. edu! bug-gnu-emacs On 
U U C Pnet), for reporting emacs bugs and fixes. B ut before reporting something as a bug, please try to be sure that it really is a 
bug, not a misunderstanding or a deli berate feature. We ask you to read the section "Reporting emacs Bugs" near the end of 
the reference manual (or into system) for hints on how and when to report bugs. Also, include the version number of the 
emacs you are running in every bug report that you send in. 

Do not expect a personal answer to a bug report. The purpose of reporting bugsisto get them fixed for everyone in the next 
release, ifpossible. For personal assistance look in the service file for a list of people who offer it. 

Please do not send anything but bug reports to this mailing list. Send requests to be added to mailing lists to the special list 
info-gnu-emacs-request@prep.ai.mit.edu (or the corresponding U U C P address). For more information about emacs mailing 
lists, seethefile /usr/iocai/emacs/etc/MAiuNGLisTs. Bugs tend actually to be fixed if they can be isolated, so itisin your 
interest to report them in such away that they can be easily reproduced. 

One bug that I know about: Shell will not work with programs running in Raw mode on someU NIX versions. 

UN RESTRICTIONS 

emacs i s free; anyone may redistribute copies of emacs to anyone under the terms stated in the emacs General Public License, a 
copy of which accompanies each copy of emacs and which also appears in the reference manual. 

Copies of emacs may sometimes be received packaged with distributions of U N IX systems, but it is ns/er included in the 
scope of any license covering those systems. Such inclusion violates the terms on which distribution is permitted. In fact, the 
primary purpose of the General Public License is to prohibit anyone from attaching any other restrictions to redistribution 
Of emacs. 

Richard Stallman encourages you to improve and extend emacs, and urges that you contribute your extensions to theGN U 
library. Eventually GN U (G N U 's N ot UN IX) will beacomplete replacement for Berkeley U NIX. Everyonewill be free to 
use, copy, study, and changetheGN U system. 

SEE ALSO 

x( 1), xlsfonts(l), xterm(l), xrdb(l) 

AUTHORS 

emacs was written by Richard Stallman and the Free Software Foundation. Joachim M artillo and Robert Krawitz added theX 
features. 

19 April 1994 
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emacstool 

emacstooi— Run emacs under Sun windows with function key and mouse support. 

SYNOPSIS 

emacstool [{window_args} {-rc run_command_path} args ... ] 

TYPICAL USAGE 

In '/. suntoois or '/.rootmenu, include a line like this: 

"Emacstool" emacstool -WI emacs.icon -f emacstool-init 

DESCRIPTION 

emacstool creates a SunV iew frame and a tty subwindow within which mouse events and function keys are translated to 
ASCII sequences that emacs can parse. The translated input events are sent to the process running in the tty subwindow, 
which is typically GN U emacs. emacstool thereby allows GN U emacs users to make full use of the mouse and function keys. 
GNU emacs can be loaded with functions to interpret the mouse and function-key events to make a truly fine screen-oriented 
editor for the Sun W orkstation. 



NOTE 


GNU emacs has a special interface to theX Window System as well. TheX Window System has many technical advan¬ 
tages, itisan industry standard, and itisalsofreesoftware.TheFreeSoftwareFoundation urges you totryX Windows, 
and distributes a free copy of x on emacs distribution tapes. 


Function keys are translated to a sequence of the form / V[a-o][irt]. The last character isi, r, ort, corresponding to 
whether the key is among the Left, Right, orT op function keys. The third character indicates which button of the group was 
pressed. Thus, thefunction key in thelower-right corner will transmit the sequence ~x*or. In addition, the [in] i s affected 
by the Control, M eta, and Shift keys. Unshifted Ctrl keys will be nonalphabetic: C-l is [,], C-r is [ 2 ], C-t is [4], 

M ouse buttons are encoded as 'x*@( [ 124] x y)\n. 'x"@ is the standard GN U emacs mouse event prefix; it is followed by a list 
indicating the button pressed and the character row and column of the point in the window where the mouse cursor is, and 
followed by a newline character. In GN U emacs, the 'x'@ dispatches to a mouse event handler which then reads the following 
list. 

OPTIONS 

emacstool supports all thestandard window arguments including font and icon specifiers. 

By default, emacstool runs the program emacs in thecreated subwindow. The value of the environment variable emacstool 
can be used to overridethis if your version of emacs is not accessible on your search path by the name emacs. In addition, the 
run command can beset by the pathname following the last occurrence of the -rc flag. This is convenient for using emacstool 
to run on remote machines. 

All other command-line arguments not used by the window system are passed as arguments to the program that runs in the 
emacstool window. 

For example, 

local% (emacstool -rc rlogin remote -8 &)& 

will create an emacstool window logged in to a machine named remote. If emacs is run from thiswindow, emacstool will 
encode mouse and function keys, and send them to rlogin. If emacs is run from this shell on the remote machine it will see 
the mouse and function keys properly. H owever, since the remote host does not have access to the screen, the cursor cannot 
be changed, menus will not appear, and the selection buffer (stuff) is limited. 
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USING WITH GNU emacs 

T he G N U emacs files lisp/term/sun. el, lisp/sun-mouse, el, lisp/sun -f ns. el, and src/sunf ns.c provide emacs Support 
for theemacstooi and function keys, emacstooi will automatically set the term environment variable to be sun and unset 
the environment variable termcap. That is, these variables will not be inherited from the shell that starts emacstooi. Si nee the 
terminal type is sun (that is, the environment variable term is set to sun), emacs will automatically load the fi le usp/term/sun. 
This, in turn, will ensure that sun-mouse, ei isautoloaded when any mouse events are detected. It is suggested that sun-mouse 
and sun -t ns be loaded in your site-imt.ei file, so that they will always be loaded when running on a Sun workstation. 

In addition, emacstooi sets the environment variable in_emacstool = “t". Lisp codein your '/.emacs can use (getenv 

"in emacstool") to determine whether to do emacstooi-specific initialization, sun.ei uses this to automatically call emacstooi- 

init if (getenv "IN EMACSTOOL" ) is defined. 

The file src/sunf ns.c defines several useful functions for emacs on the Sun. Among these are procedures to pop up SunView 
menus, put and get from the SunView stuff buffer, and a procedure for changing the cursor icon. If you want to define or 
edit cursor icons there is a rudimentary mouse-driven icon editor in thefileiisp/sun-cursors.ei. T ry invoking (sc:edit- 

cursor). 

BUGS 

Ittakesafew milliseconds to createamenu before it pops up. 

ENVIRONMENT VARIABLES 

EMACSTOOL, IN_EMACSTOOL, TERM, TERMCAP 

FILES 


emacs 

SEE ALSO 

emacs(l), .../etc/SUN-SUPPORT, .../lisp/term/sun.el 

etags 

etags — G enerate tag fi le for emacs 
etags— G enerate tag fi le for vi 

SYNOPSIS 

etags [ -aCDSVH] [ -i f i I e ][—o t agfiIe ] 

[ --C++ ] [ --no-defines] [ --ignore-indentation ] [ --help ] [ --version ] 

[ --include=f i I e ] [ --output=tagf i I e ] [ --append ] file ... 

etags [ -aCdSVH] [ -BtTuvwx ] [ -o tagfile ] 

[ --C++ ] [ --defines ] [ --ignore-indentation ] 

[ --backward-search] [ --forward-search ] [ --typedefs ] [ --typedefs-and-c++] 

[ --no-warn ] [ --cxref ] [ --help ] [ --version ] 

[ --output=tagf i I e ] [ --append ] [ --update ] file ... 

DESCRIPTION 

The etags program is used to create a tag table file, in a format understood by emacs(l); the etags program is used to create a 
similar table in a format understood by vi(l) . Both forms of the program understand the syntax of C, FORTRAN, Pascal, 
LaT eX, Scheme, emacs Lisp/Common Lisp, and most assembler-like syntaxes. Both forms read the files specified on the 
command line, and write a tag table (defaults tags for etags, tags for etags) in the current working directory. The programs 
recognize the language used in an input file based on its filename and contents; there are no switches for specifying the 
language. 
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OPTIONS 

Some options make sense only for the vi- style tag files produced by ctags; etags does not recognize them. The programs 

accept unambiguous abbreviationsfor long option names. 

-a, -append Append to existing tag fi le. (For vi-format tag files, see also -update.) 

-b, -backward-search T ag files written in the format expected by vi contain regular expression search instructions; 

the-B option writes them using the delimiter ?, to search backwards through files. The 
default isto use the delimiter / to search forwards through files. Only ctags accepts this 
option. 

-c, --c++ Treat files with ,c and .h extensions as C++code, note code. Fileswith .c, .h, .cxx, .hxx, 

or .cc extensions are always assumed to beC++code. 

-d, -defines C reate tag entri es for C preprocessor definitions, too. This is the default behavior for etags, 

so this option is only accepted by ctags. 

-d, -no-defines D o not create tag entries for C preprocessor definitions. This may make the tags file much 

smaller if many header files are tagged. This is the default behavior for ctags, so this option 
is only accepted by etags. 

-i file, --inciude=f i i e I nclude a note in tag fi le indicating that, when searching for a tag, oneshould also consult 

the tags filer i i e after checking the current file. Only etags accepts this option. 

-o tagfiie, --outputs agf i i e Explicit name of file for tag table; overrides default tags or tags. (But ignored with -v or 
-x.) 


-S, --ignore-indentation 

-t, --typedefs 

-T, --typedefs-and-c++ 

-u, - -update 

-v, - -vgrind 

-w, --no-wann 

-x, - -cxref 

-H, - -help 
-V, - -version 


Don't rely on indentation as much as we normally do. Currently, this means not to assume 
that a closing brace in the first column isthefinal brace of a function or structure definition 
in C and C++. 

Record typedefs in C code as tags. Since this isthe default behavior of etags, only ctags 
accepts this option. 

Generate tag entries for typedefs, struct, enum, and union tags, and C++ member functions. 
Si nee this is the default behavior of etags, only ctags accepts this option. 

Updatetag entries for files specified on command line leaving tag entries for other files in 
place. Currently, this is implemented by deleting the existing entries for the given files and 
then rewriting the new entries at the end of the tags file. It i s often faster to simply rebuild 
the entire tag file than to use this. Only ctags accepts this option. 

Instead of generating a tag file, write index (in vgrind format) to standard output. Only 
ctags accepts this option. 

Suppress warning messages about duplicate entries. The etags program does not check for 
duplicateentries, so this option isnot allowed with it. 

Instead of generating a tag file, write a cross-reference (in cxref format) to standard output. 
Only ctags accepts this option. 

Print usage information. 

Print the current version of the program (same as the version oftheemacs etags is shipped 
with). 


SEE ALSO 

emacs entry in info; GNU EmacsM anual, Richard Stallman. 
cxref(l), emacs(l), vgrind(l), vi(l). 


COPYING 

Copyright © 1992 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this 
manual provided thecopyright notice and this permission notice are preserved on all copies. 

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 
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Permission is granted to copy and distribute translations of this manual into another language, under the above conditions 
for modified versions, except that this permission notice may be included in translations approved by the Free Software 
Foundation instead of in the original English. 

GNU Tools, 19 April 1994 

expand 

expand— C onvert tabsto spaces 

SYNOPSIS 

expand [-tabl[ ,ta b 2 [,...]]] [-t tabl [ ,ta b 2 [,...]] ] [-i ] [—tabs=tabl[,ta b 2 [,...]]] 

[--initial] [--help] [--version] [file...] 

DESCRIPTION 

This manual page documents the GN U version of expand, expand writes the contents of each given file, or the standard input 
if none are given or when a file named - is given, to the standard output, with tab characters converted to the appropriate 
number of spaces. By default, expand converts all tabsto spaces. It preserves backspace characters in the output; they 
decrement the column count for tab calculations The default action is equivalent to -8 (set tabs every 8 columns). 

OPTIONS 

-t, - -tabs t abl [ ,t a b2 [,...] ] 


-i, - - initial 

- -help 

- -version 

GN U Text Utilities 

find 

find— Search forfilesin a directory hierarchy 

SYNOPSIS 

find [path...] [expressi on ] 

DESCRIPTION 

This manual page documents the GN U version of find, find searches the directory tree rooted at each given filename by 
evaluating the given expression from left to right, according to the rules of precedence (see "Operators," later in this manual 
page), until the outcome is known (the left side is False for and operations, True for or), at which point find moves on to the 
next filename. 

Thefirst argument that begins with-, (, >, ,,ori istakento be the beginning of the expression; any arguments before it are 
paths to search, and any arguments after it are the rest of the expression. If no paths are given, the current directory is used. If 
no expression is given, the expression -print is used. 

find exits with status 0 if all files are processed successfully, greater than 0 if errors occur. 


If only onetab stop isgiven, set th e tabs t a b 1 spaces apart instead of the default 8 . 
Otherwise, set the tabs at columns t a b 1, t a b 2 , and so forth (numbered from 0 ) and 
replace any tabs beyond the tab stops given with single spaces. If the tab-stops are 
specified with the-t or - -tabs option, they can be separated by blanks as well as by 
commas. 

Only convert initial tabs (those that precede all nonspace or tab characters) on each 
line to spaces. 

Print a usage message and exit with a nonzero status. 

Print version information on standard output then exit. 
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EXPRESSIONS 

The expression is made up of options (which affect overall operation rather than the processing of a specific file, and always 
return True), tests (which return a True or False value), and actions (which have side effects and return a True or False value) 
all separated by operators -and is assumed where the operator is omitted. If the expression contains no actions other than - 
prune, -print is performed on all files for which theexpression is true. 


OPTIONS 


All options always return True. They always take effect, rather than being processed only when their place in theexpression is 
reached. Therefore, for clarity, i t i s best to pi ace them at the beginning of theexpression. 


-daystart 

-depth 
-follow 
-help, -help 
-maxdepth I evel s 

-mindepth I evel s 

-mount 

-noleaf 


-version, —version 
-xdev 


M easure times (for -amin, -atime, -cmin, -ctime, -mmin, and -mtime) from the beginning of today 
rather than from 24 hours ago. 

Process each directory's contents before the directory itself. 

Dereference symbolic I inks I implies -noleaf. 

Print a summary of the command-line usage of find and exit. 

Descend at most i evel s (a non negative integer) levels of directories below the command-line 
arguments, -maxdepth 0 means only apply the tests and actions to the command-line arguments. 

Do not apply any tests or actions at levels less than 1 evel s (a nonnegative integer), -mindepth 1 
means process all fi les except the command-line arguments. 

Don't descend directories on other filesystems. An alternate name for -xdev, for compatibility with 
some other versions of find. 

Do not optimize by assuming that directories contain two fewer subdirectories than their hard link 
count. This option is needed when searching filesystems that do not follow theLI NIX directory- 
link convention, such as CD-ROM or M S-D OS filesystems or AFS volume mount points. Each 
directory on a normal U NIX filesystem has at least 2 hard links: its name and its. entry. Addition¬ 
ally, its subdirectories (if any) each havea .. entry linked to that directory. W hen find isexamining 
a directory, after it has statted two fewer subdirectories than the directory's link count, it knows 
that the rest of the entries in the directory are nondirectories (leaf files in the directory tree). If 
only the files' names need to be examined, there is no need to stat them; this gives a significant 
increase in search speed. 

Print the find version number and exit. 

D on't descend directories on other filesystems. 


TESTS 


N umeric arguments can be specified as 


+n 

-n 

n 

-amin n 
-anewer file 

-atime n 
-cmin n 
-cnewer file 

-ctime n 

-empty 

-false 


G reater than n. 

Less than n. 

Exactly n. 

File was last accessed n minutes ago. 

File was last accessed more recently than file was modified, -anewer is affected by -follow only if- 
follow comes before -anewer on the command line. 

File was last accessed n*24 hours ago. 

File's status was last changed n minutes ago. 

File's status was last changed more recently than filewas modified, -cnewer is affected by -follow 
only if -follow comes before -cnewer on the command line. 

File's status was last changed n*24 hours ago. 

File is empty and is either a regular file or a directory. 

Always false. 
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-fstype type 


-gid n 

-group g n a me 
-ilname pattern 
-iname pattern 

-inum n 

-ipath pattern 
-iregex pattern 
-links n 
-Iname pattern 

-mmin n 
-mtime n 
-name pattern 


-newer file 

-nouser 
-nogroup 
-path pattern 


-perm mode 

-perm -mode 
-perm +mode 
-regex pattern 


-size n[bckw] 


-true 
-type c 


File is on a filesystem of type type. The valid filesystem types vary among different versions of 
UN IX; an incomplete list of filesystem types that are accepted on some version of U NIX or another 
is: uf s, 4.2,4.3, nfs, tmp, mfs, ssiK, S 52 K. You can use-printf with the %f directive to seethetypes 
of your filesystems. 

File's numeric group ID is n . 

File belongs to group g na me (numeric group ID allowed). 

Like -iname, but the match is case-in sensitive. 

Like-name, but the match is case-insensitive. For example, the patterns to* and f?? match the 
filenames foo, foo, too, too, and so on. 

Filehas inode numbern. 

Like-path, but the match is case-insensitive. 

Like -regex, but the match iscase-insensitive. 

Filehasn links 

File is a symbolic link whose contents match shell pattern pattern. The metacharacters do not treat 
/ or. specially. 

File's data was last modified n minutes ago. 

File's data was last modified n *24 hours ago. 

Base of filename (the path with the leading directories removed) matches shell pattern pattern. The 
metacharacters)*, ?, and n) do not match a . at the start of the base name. T 0 ignore a directory 
and the files under it, use -prune; see an example in the description of -path. 

File was modified more recently than file, -newer is affected by -follow only if -follow comes before 
-newer on the command line. 

N 0 user corresponds to file's numeric user ID. 

N 0 group corresponds to file's numeric group ID. 

Filename matches shell pattern pattern. The metacharacters do not treat / or. specially; so, for 
example, 

find. - path './sr*sc' 

will print an entry for a directory called ,/src/misc (if one exists). T 0 ignoreawholedirectorytree, 
use-prune rather than checking every file in the tree. For example to skip the directory src/emacs 
and all files and directories under it, and print the names of the other filesfound, do something like 
this 

find . -path './src/emacs' -prune-o -print 

File's permission bits are exactly mode (octal or symbolic). Symbolic modes use mode 0 as a point 
of departure. 

All of the permission bits mode are set for the file. 

Any of the permission bits mode are set for the file 

Filename matches regular expression pattern. Thisisa match on the whole path, notasearch. For 
example, to match a file named ./fubars, you can use the regular expression ,*bar. or. *b.*3, but 
not b.*r 3 . 

Fileusesn units of space. The units are 512-byte blocks by default or if b follows n, bytes if c 
follows n , kilobytes if k follows n, or 2-byte words if w follows n . The size does not count indirect 
blocks, but it does count blocks in sparse files that are not actually allocated. 

Always true. 

File is of type c. Possible types: 
b Block (buffered) special 
c C haracter (unbuffered) special 
d Directory 
p Named pipe(FIFO) 
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-uid n 
-used n 
-user uname 
-xtype c 


f Regular file I symbolic link 
s Socket 

File's numeric user ID isn. 

Filewas last accessed n days after its status was last changed. 

Fileisowned by user uname (numeric user ID allowed). 

The same as -type unless the file is a symbolic link. For symbolic links: if -follow has not been 
given, True if the file is a link to a fi le of type c ; if -follow has been given, True if c isi. In other 
words, for symbolic links -xtype checks the type of the file that -type does not check. 


ACTIONS 

-exec command; 


-fIs file 
-fprint file 


-fprintO file 
-fprintf file f or mat 
-ok command; 

-print 

-print© 


-printf f or mat 


Execute command; True if 0 status is returned. All following arguments to find are taken to be 
arguments to the command until an argument consisting of; is encountered. The string {} is 
replaced by the current filename being processed everywhere it occurs in the arguments to the 
command, not just in arguments where it is alone, as in some versions of find. Both of these 
constructions might need to be escaped (with a \) nor quoted to protect them from expansion by 
the shell. The command isexecuted in thestarting directory. 

True; like -is but write to file like -fprint. 

True; print the full filename into file fi i e. If f i i e does not exist when find is run, it is created; if it 
does exist, it istruncated. Thefilenames /dev/stdout and /dev/stderr are handled specially; they 
refer to the standard output and standard error output, respectively. 

True; like -print® but Write to file like -fprint. 

True; like -printf but Write to file like -fprint. 

Like -exec but ask the user first (on the standard input); if the response does not start with y ory, 
do not run the command, and return False. 

True; print the full filename on the standard output, followed by anewline. 

True; print the full filename on the standard output, followed by a null character. This allows 
filenames that contain newlines to be correctly interpreted by programs that process the find 
output. 

True; print format on the standard output, interpreting n escapes and % directives. Field widths and 
precisions can be specified aswith theprintf C function. U nlike -print, -printf does not add a 
newline at the end of the string. The escapes and directives areas follows: 

\a Alarm bell 
\b Backspace 

\c Stop printing from this format immediately and flush the output 

\f Formfeed 

\n Newline 

\r Carriage return 

\t FI orizontal tab 

\v Vertical tab 

\\ A literal backslash (V) 


A \ character followed by any other character istreated as an ordinary character, so they both are 
printed: 

%% A literal percent sign. 

%a File'slast access time in theformat returned by theC ctime function. 

%Ak File'slast access time in theformat specified by k, which is either @ or a directive for the C 
strftime function. T he possi ble values for k are listed below; some of them might not be 
available on all systems, due to differencesin strftime between systems. 

@ seconds sincej an. 1,1970, 00:00 GMT. 
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H Hour(00..23) 

i H our ( 01 .. 12 ) 

k Hour(0..23) 

1 Hour ( 1 .. 12 ) 

m Minute (00..59) 

p Locale'sa.m. or p.m. 

r Time, 12-hour (hh:mm:ss [AP]M> 

u Second (00. .61) 

T Time, 24-hour (hh:mmrss) 

x Locale'stimerepresentation (h:m:s) 

z Time zone (for example EDT), or nothing if no time zone is 

determinable 


Date fields 

a Locale's abbreviated weekday name(sun. .sat) 

a Locale's full weekday name, variable length (Sunday. .Saturday) 

b Locale's abbreviated month name(jan. .Dec) 

b Locale's full month name, variable length (January.. December) 

c Locale's date and time (sat Nov 04 12:02:33 est igsg) 

d Day of month (01. .31) 

D D ate (mm/dd/yy) 

h Same as b 

j D ay of year (001.. 366 ) 

m M onth (01. .12) 

u Week number of year with Sunday as first day of week (00..53) 

w D ay of week (0. .e) 

w Week number of year with M onday as first day of week (00. .53) 

x Locale's date representation (mm/dd/yy) 

y Last two digits of year (00. .99) 

v Year (1970...) 

%b File'ssizein 512-byte blocks (rounded up). 

%c File's last status change time in the format returned bytheC ctime function. 

%ck File's last status change time in the format specified by k, which isthesameasfor%A. 
%d File's depth in the directory tree; 0 means the file is a command-line argument. 

%f File'snamewith any leading directories removed (only the last element). 

%f Type of the filesystem thefileison; thisvaluecan be used for-tstype. 

%g File'sgroup name, ornumeric group ID if the group has no name. 

%g File's numeric group ID. 

%h Leading directories of file's name (all but the last element). 

%h Command-lineargumentunderwhich filewasfound. 

%i File's inode number (in decimal). 

%k File'ssizein IK blocks (rounded up). 

%i 0 bject of symbolic link (empty string if file is not a symbolic link). 
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%m File's permission bits (in octal). 

%n N umber of hard links to file. 

%p File's name 

%p File's name with the name of the command-line argument under which it was found 
removed. 

%s File's size in bytes. 

%t File's last modification time in theformat returned bytheC ctime function. 

%Tk File's last modification time in theformat specified by k, which is the same as for %a. 

%u File's username, or numeric user ID if the user has no name 
%u File's numeric user ID. 

A % character followed by any other character is discarded (but the other character is 
printed). 

-prune If -depth is not given, True; do not descend the current directory. 

If -depth isgiven, False; no effect. 

-is True; list current file in is -diis format on standard output. The block counts are of IK blocks, 

unless the environment variable posixly_correct is set, in which case512- byte blocks are used. 


OPERATORS 


Listed in order of decreasing precedence 
< expr ) Force precedence. 

! expr True if expr is false. 


-not expr 
expr1 expr 2 
expr1 -a expr2 
expr1 -and expr2 
expr1 -o expr2 
expr 1 -or expr2 
expr1, expr2 


Sameas : expr. 

And (implied); expr 2 is not evaluated if expr 1 isfalse. 

Sameasexpri expr2. 

Sameasexprl expr 2 . 

Or; expr 2 is not evaluated if expr 1 is true. 

Same as expr 1 -0 ex pr 2 . 

List; both expr 1 and ex pr 2 are always evaluated. T he value of ex p r 1 is discarded; the value of the list 
is the value of ex pr 2 . 


SEE ALSO 

locate(lL), locatedb(5L), updatedb(lL), xargs(lL) Finding Files (online in info, or printed) 

GNU FileUtilities 

fitstopnm 

fitstopnm— C onvert a FITS file into a portable anymap 

SYNOPSIS 

fitstopnm [-image N][-noraw][-scanmax][-printmax][-min f][-max f][FI TSfi I e] 

DESCRIPTION 

Reads a FITS fi le as i nput. Produces a portable pixmap if the F IT S file consists of 3 image planes (naxis = 3andNAxis3 = 3), 
a portable graymap if the FITS file consists of 2 image planes (naxis = 2 ), or whenever the -image flag is specified. The 
results may need to be flipped top for bottom; if so, just pipe the output through pnmfiip -tb. 
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OPTIONS 

The - image option isfor FITS files with three axes. The assumption is that the third axis is for multiple images, and this 
option lets you select which one you want. 

Flags -min and -max can be used to override the min and max values as read from the FITS header or the image data if no 
datamin and datamax keywords are found. Flag -scanmax can be used to force the program to scan the data even when datamin 
and datamax are found in theheader. If -printmax isspecified, theprogram will just printthemin and max values and quit. 
Flag - noraw can be used to force the program to produce an ASCII portable anymap. 

Theprogram will tell what kind of anymap is writing. All flags can be abbreviated to their shortest unique prefix. 

REFERENCES 

FITS stands for Flexible I mage T ransport System. A full description can be found in Astronomy & Astrophysics Supplement 
Series44 (1981), page 363. 

SEE ALSO 

pnmtofits(l), pgm( 5 ), pnmflip(l) 

AUTHOR 

Copyright © 1989 byjef Poskanzer, with modifications by Daniel Briggs (dbriggs@nrao.edu) and Alberto Accomazzi 

(alberto@cfa.harvard.edu) 

20 September 1989 

fmt 

tmt— Adjust line-length for paragraphs of text 

SYNOPSIS 

fmt [-wi dth][fi I es]... 

DESCRIPTION 

fmt is a simple text formatter. It inserts or deletes newlines, as necessary, to make all lines in a paragraph be approximately the 
samewidth. It preserves indentation and word spacing. 

The default line width is 72 characters. You can override this with the -width flag. If you don't name any files on the 
command line, then fmt will read from stdin. 

It is typically used from within vi to adjust the line breaks in a single paragraph. To do this, move the cursor to the top of 
the paragraph, type igfmt, and press Return. 

AUTHOR 

Steve Kirkendall (kirkenda@cs.pdx.edu) 

fold 

fold— Wrap each input lineto fit in specified width 

SYNOPSIS 


fold [-bs] [-w width] [—bytes] [—spaces] [ — width=wi dt h ] [—help] 
[ —version] [file...] 
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DESCRIPTION 

This manual page documents the GN U version of told, fold prints the specified files, or the standard input when no files are 
given or the filename - is encountered, on the standard output. It breaks long lines into multiple shorter lines by inserting a 
newline at column 80. It counts screen columns, so tab characters usually take more than one column, backspace characters 
decrease the column count, and carriage return characters set the column count back to zero. 

OPTIONS 

-b, —bytes 
-s, -spaces 

-w, —width wi dt h 

— help 

— version 

GN U Text Utilities 

free 

free— D isplay amount of free and used memory in the system 

SYNOPSIS 

free [-b | -k ] -m] [- 0 ] [-s delay] [-t] 

DESCRIPTION 

free displays the total amount of free and used physical and swap memory in the system, as well as the shared memory and 
buffers used by the kernel. 

OPTIONS 

The -b switch displays the amount of memory in bytes; the -k switch (set by default) displays it in kilobytes; the -m switch 
displays it in megabytes. 

The -t switch displays a line containing thetotals 

The -0 switch disables the display of a "buffer adjusted" line. Unless specified free subtracts/adds buffer memory from/to the 
used/free memory reports (respectively!). 

The -s switch activates continuous polling delay seconds apart. You may actually specify any floating point number for 
delay, usieep(3) is used for microsecond resolution delaytimes. 

FILES 

/proc/meminfo M emory i nformation 

SEE ALSO 

ps(l), top(l) 

AUTHORS 

Brian Edmonds 

Cohesive Systems, 20 M arch 1993 


Count bytes rather than columns, so that tabs, backspaces, and carriage returns are each counted as 
taking up one column, just like other characters. 

Break at word boundaries. If the line contains any blanks, the line is broken after the last blank that 
falls within themaximum linelength. If there are no blanks the line is broken at the maximum 
line length, as usual. 

Use a maximum linelength of width columns instead of 80. 

Print a usage message and exit with a nonzero status. 

Print version information on standard output then exit. 
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fsinfo 

fsinto—x font server information utility 

SYNOPSIS 

fsinfo [-server servername] 

DESCRIPTION 

fsinfo is a utility for displaying information about an X font server. It is used to examine the capabilities of a server, the 
predefined values for various parameters used in communicating between clients and the server, and the font catalogues and 
alternate servers that are avai lable. 

EXAMPLE 

The following is a sample produced by fsinfo. 

name of server: hansen:7100 
version number: 1 

vendor string: Font Server Prototype 
vendor release number: 17 

maximum request size: 16384 longwords (65536 bytes) 

number of catalogues: 1 

all 

Number of alternate servers: 2 
#0 hansen:7101 
#1 hansen:7102 
number of extensions: 0 

ENVIRONMENT 

fontserver T o get the default fontserver 

SEE ALSO 

xfs(l), fslsfonts(l) 

AUTHOR 

D ave Lemke (N etwork C omputing D evices, I nc.) 

X Version 11 Release6 

fslsfonts 

fslsfonts— List fonts served by X font server 

SYNOPSIS 

fslsfonts [-options ...] [-fn pattern] 

DESCRIPTION 

fslsfonts lists the fonts that match the given pattern. The wildcard character * may be used to match any sequence of 
characters (i ncluding none), and ? to match any single character. If no pattern isgiven, * isassumed. 

The* and ? characters must be quoted to prevent them from being expanded by the shell. 

OPTIONS 

-server host: port T his option specifies the X font server to contact. 

-l L ists some attributes of thefonton onelinein addition to its name. 
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-n 
-in 

-m 

-C 
-1 

-w width 

-n col umns 

-u 

SEE ALSO 

xfs(l), showfont(l), xlsfonts(l) 

ENVIRONMENT 

fontserver T o get the default host and port to use 

BUGS 

Doing fsistonts -l can tie up your server for a very long time. This is really a bug with single-threaded nonpreemptable 
servers, notwith thisprogram. 

AUTHOR 

D ave Lemke (N etwork C omputing D evices, I nc.) 

X Version 11 Release6 1 

fstobdf 

fstobdf— G enerate B D F font from X font server 

SYNOPSIS 

fstobdf [ -server server ] -fn f o n t n a me 

DESCRIPTION 

The fstobdf program reads a font from a font server and prints a B D F file on the standard output that may be used to 
recreate the font. This is useful in testing servers, debugging font metrics, and reproducing lost BDF files. 

OPTIONS 

-server ser verna me This option specifies the server from which the font should be read. 

-fn f o n t n a me This option specifiesthe font for which aBDF fileshould be generated. 

ENVIRONMENT 

fontserver D efault server to use 

SEE ALSO 

xfs(l), bdftopcf(l), fslsfonts(l) 


Lists font properties in addition to -l output. 

Supported for compatibi lity with xisfonts, but output is the same as for -n. 

This option indicates that long listings should also print the minimum and maximum bounds of 
each font. 

This option indicates that listings should use multiple columns. This is the same as -n 0 . 

This option indicates that listings should use a single column. This is the same as -n 1. 

Thisoption specifies the width in characters that should beused in figuring out how many 
columns to print. The default is 79. 

Thisoption specifies the number of columns to use in displaying the output. The default is 0 , 
which will attempt to fit as many columns of font names into the number of character specified by 
-w width. 

Thisoption indicates that the output should be left unsorted. 
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AUTHOR 

Olaf Brandt (N etwork Computing Devices), DaveLemke(N etwork Computing Da/ices), Jim Fulton (M IT X Consortium) 
X Version 11 Release6 

fstopgm 

fstopgm— C onvert a U senix FaceSaver file into a portable graymap 

SYNOPSIS 

fstopgm [f s fiIe ] 

DESCRIPTION 

Reads a U senix FaceSaver fi le as input. Produces a portable graymap as output. 

FaceSaver files sometimes have rectangular pixels. Although fstopgm won't rescalethem into square pixelsfor you, it will give 
you the precise pnmscale command that will do the job. Because of this, reading a FaceSaver image is a two-step process. 
First you do 
fstopgm > /dev/null 

This will tell you whether you need to use pnmscale. Then use one of the following pipelines: 
fstopgm | pgmnorm 

fstopgm | pnmscale -whatever | pgmnorm 

To go to PBM, you want something more like one of these: 

fstopgm [ pnmenlarge 3 | pgmnorm | pgmtopbm 

fstopgm | pnmenlarge 3 | pnmscale <whatever> | pgmnorm | pgmtopbm 

You want to enlarge when going to a bitmap because otherwise you lose information; but enlarging by more than 3 does not 
look good. 

FaceSaver isa registered trademark of M etron Computerware Ltd. of Oakland, CA. 

SEE ALSO 

pgmtofs(l), pgm(5), pgmnorm(l), pnmenlarge(l), pnmscale(l), pgmtopbm(l) 

AUTHOR 

Copyright© 1989 byjef Poskanzer 
6 April 1989 

ftp 

ftp— ARPAnet file transfer program 

SYNOPSIS 

ftp [-v] [-d] [-i] [-n] [-g] [host ] 

DESCRIPTION 

ftp is the user interface to the ARPAnet standard File T ransfer Protocol. The program allows a user to transfer files to and 
from a remote network site. 

Options may be specified at the command line, or to the command interpreter. 
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-v Verbose option forces ftp to show all responses from the remote server, aswell as 

report on data transfer statistics. 

-n Restrains ftp from attempting auto-login upon initial connection. If auto-login is 

enabled, ftp will check the (see below) file in the user's home directory for an entry 
describing an account on the remote machine. If no entry exists, ftp will prompt for 
theremotemachinelogin name(default istheuser identity on thelocal machine), 
and, if necessary, prompt for a password and an accountwith which to login. 

-i T urns off interactive prompting during multiple file transfers. 

-d Enables debugging. 

-g D isables filename globbing. 


The client host with which ftp is to communicate may be specified on the command line. If this is done, ftp will immedi¬ 
ately attempt to establish a connection to an FTP server on that host; otherwise, ftp will enter itscommand interpreter and 
await instructions from the user. W hen ftp is awaiting commands from the user, the prompt 

ftp> 


is provided to the user. The following commands are recognized by ftp: 


! [command ] [args ] 

$ ma c r o - n a me [args] 
account [passwd] 

append local-file [r emot e-f i I e ] 


ascii 

bell 

binary 

bye 

case 

cd r emot e - di r ect or y 
cdup 

chmod mode f i I e - name 
close 

cr 


Invoke an interactive shell on the local machine. If there are arguments, the first is 
taken to be a command to execute directly, with the rest of the arguments as its 
arguments. 

Execute the macro ma c r o ■ n a me that was defi ned with the macdef command. 
Arguments are passed to the macro unglobbed. 

Supply a supplemental password required by a remote system for access to resources 
once a login has been successfully completed. If no argument is included, the user 
will be prompted for an account password in a nonechoing input mode. 

Append a local file to a file on the remote machine. If r emot e-f i i e is left unspecified, 
thelocal filename is used in naming the remote file after being altered by anyntrans 
or nmap setting. File transfer uses the current settings for type, format, mode, and 
structure. 

Set the file transfer type to network ASC11. T his is the default type. 

Arrange that a bell be sounded after each file transfer command is completed. 

Set the file transfer type to support binary image transfer. 

T erminatetheFTP session with the remote server and exit ftp. An end of file will 
also terminate the session and exit. 

T oggle remote computer filename case mapping during mget commands. W hen case 
is on (default is off), remote computer filenames with all letters in upper case are 
written in the local directory with the letters mapped to lowercase. 

Change the working directory on the remote machine tor emot e- di rectory. 

C hange the remote machine working directory to the parent of the current remote 
machine working directory. 

Change the permission modes of thefilef i i e- name on the remote system to mode. 
Terminate the FTP session with the remote server, and return to the command 
interpreter. Any defined macros are erased. 

T oggle carriage return stripping during ASCII type file retrieval. Records are 
denoted by a carriage return/linefeed sequence during ASCII type file transfer. 
When cr is on (the default), carriage returns are stripped from this sequence to 
conform with theLI N IX single linefeed record delimiter. Recordson non-U N IX 
remote systems may contain single linefeeds; when an ASCII type transfer is made, 
these linefeeds may be distinguished from a record delimiter only when cr is off. 
Deletethefileremote.fi i e on the remote machine. 


delete r emot e- f i I e 
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debug [debug-vai ue ] T oggle debuggi ng mode. If an optional debug-vai ue is specified, it is used to set the 

debugging level. W hen debugging is on, ftp prints each command sentto the 
remote machine preceded by the string ->. 

dir [remote-directory] [I oca I -f i I e ] Print a listing Of the directory contents in the directory, remote-di rectory, and, 

optionally, placing the output in i ocai-file. If interactive prompting is on, ftp will 
prompt the user to verify that the last argument is indeed the target local file for 
receiving dir output. If no directory is specified, the current working directory on 
the remote machine is used. If no local file is specified, or i ocai - f i i e is -, output 
comes to theterminal. 
disconnect A Synonym for close. 

form format Set the file transfer form to f or mat . T he default f or mat is file. 


get r emot e- f i I e [I ocai - f i I e ] 


glob 


hash 

help [command ] 
idle [seconds ] 
led [directory] 

Is [remote-directory] [local-file] 


maedef macr o - name 


Retrieve ther emot e-f i i e and store it on thelocal machine. If the local filename is 
not specified, it is given the same name it has on the remote machine, subject to 
alteration by the current case, ntrans, and nmap settings. The current settings for 
type, form, mode, and structure are used while transferring thefile. 

T oggle filename expansion for mdeiete, mget, and mput. If globbing is turned off with 
giob, the filename arguments are taken literally and not expanded. Globbing for mput 
is done as in esh i. For mdeiete and mget, each remote filename is expanded 
separately on the remote machine and the lists are not merged. Expansion of a 
directory name islikely to be different from expansion ofthenameof an ordinary 
file: the exact result depends on the foreign operating system and FTP server, and 
can be previewed by doing mis remote-files N ote: mget and mput are not meant to 
transfer entire directory subtrees of fi les. T hat can be done by transferring a tar i 
archive of the subtree (in binary mode). 

Toggle hash-sign (#) printing for each data block transferred. The size of a data block 
is 1024 bytes. 

Pri nt an informative message about the meani ng of c o mma n d. I f no argument is given, 
ftp prints a list of the known commands. 

Set the inactivity timer on the remote server to seconds seconds. If seconds is 
omitted, the current inactivity timer is printed. 

Change the working directory on thelocal machine. If no directory is specified, the 
user's home directory isused. 

Print a listing of the contents of a directory on the remote machine T he listi ng 
includes any system-dependent information that the server chooses to include for 
example, mostsystemswill produce output from thecommand is 1 . (See also 
niist.) Ifremote-directory is left unspecified, the current working directory isused. 

If interactive prompting is on, ftp will prompt the user to verify that the last 
argument is indeed the target local file for receiving is output. If no local file is 
specified, or if i ocai - f i i e is-, the output is sent to theterminal. 

Define a macro. Subsequent lines are stored as the macro macro-name; a null line 
(consecutivenewlinecharactersinafileorcarriagereturnsfromtheterminal) 
terminates macro input mode. T here is a limit of 16 macros and 4096 total 
characters in all defined macros. M acros remain defined until a close command is 
executed. T he macro processor interprets $ and \ as special characters. A $ followed 
by a number (or numbers) is replaced by the corresponding argument on the macro 
invocation command line. A $ followed by an i signalsthat macro processor that the 
executing macro isto be looped. On the first pass$i isreplaced by the first argument 
on the macro invocation command line, on the second pass it isreplaced by the 
second argument, and so on. A \ followed by any character is replaced by that 
character. U sethe\to prevent special treatment of the$. 

Delete the r emot e-f i 16 s on the remote machine 


mdeiete [r emot e- f i I es ] 
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mdir remote-files I ocal ■ f i I e 


mget r emot e- f i I es 


mkdir di r ect or y- name 
mis remote-files local-file 


mode [mode - name ] 
modtime f i I e- name 
input I ocal - f i I es 


newer f i I e - name 


nlist [r emot e- di rectory] 
[I ocal - f i I e ] 


nmap [inpattern] out pat t er n 


ntrans [i nchars ] [outchars ] 


Like dir, except multiple remote files may be specified. If interactive prompting is 
on, ftp will prompt the user to verify that the last argument is indeed the target local 
filefor receiving mdir output. 

Expand the r emot e-f i i es on the remote machine and do a get for each filename thus 
produced. Seegiob for details on thefilename expansion. Resulting filenames will 
then be processed accordingto case, ntrans, and nmap settings. Files are transferred 
into the local working directory, which can be changed with led directory; new local 
directories can be created with imkdir directory. 

M ake a directory on the remote machine. 

Like mist, except multiple remote files may be specified, and the local-file must 
be specified. If interactive prompting is on, ftp will prompt the user to verify that 
the last argument is indeed the target local filefor receiving mis output. 

Set the file transfer mode to mode- name . T he default mode is stream mode. 
Showthelast modification timeof thefileon the remote machine. 

Expand wildcards in the list of local files given as arguments and do a put for each 
file in the resulting list. Seegiob for details of filename expansion. Resulting 
filenames will then be processed accordingto ntrans and nmap settings. 

Get the file only if the modification time of the remote file is more recent that the 
file on the current system. If thefiledoes not exist on the current system, the remote 
file is considered newer. Otherwise, this command is identical to get. 

Print a list of the files in a directory on the remote machine. If remote - di rectory is 
left unspecified, the current working directory is used. If interactive prompting is on, 
ftp will prompt the user to verify that the last argument is indeed the target local file 
for receiving niist output. If no local file is specified, or if i ocal - f i i e is-, the 
output is sent to theterminal. 

Set or unset thefilename mapping mechanism. If no arguments are specified, the 
filename mapping mechanism is unset. If arguments are specified, remote filenames 
are mapped during mput commands and put commands issued without a specified 
remote target filename. If arguments are specified, local filenames are mapped during 
mget commands and get commands issued without a specified local target filename. 
This command is useful when connecting to a non-UN IX remote computer with 
different file naming conventions or practices. T he mapping follows the pattern set 
by inpattern and outpattern. inpattern is a template for incoming filenames (which 
may have already been processed accordingto thentrans and case settings). Variable 
templating is accomplished by including the sequences $1 , $ 2 ,..., $9 in inpattern. 
Use\to prevent this special treatment of the $ character. All other characters are 
treated literally, and areused to deterrninethenmap inpattern vari able values. For 
example, given inpattern $1 .$2 and the remote filename mydata.data, $1 would have 
the value mydata, and $2 would have the value "data". The outpattern determines the 
resulting mapped filename. The sequences $ 1 , $ 2 ,...., $9 are replaced byanyvalue 
resulting from the inpattern template. The sequence $0 is replaced by the original 
filename. Additionally, the sequences eq 1 , seq 2 isreplaced by seqi ifseqi isnota 
null string; otherwise, it isreplaced by seq 2 . For example the command nmap 
$1 .$ 2.$3 [ $ 1 , $ 2 ]. [ $ 2 ,tile] would yield the output filename myfiie.data for 
input filenames my-file. data and myfiie .data, old, myfiie. file for the input 
filename my-file, and myfiie. myfiie for the input filename .myfiie. Spaces may be 
included in outpattern, as in the example: nmap $1 sed "s/ *$//■ > $ 1 . U se the \ 
character to prevent special treatment of the$, [, [, and , characters. 

Set or unset thefilenamecharacter translation mechanism. If no arguments are 
specified, thefilenamecharacter translation mechanism is unset. If arguments are 
specified, characters i n remote filenames are translated during mput commands and 



open host [port ] 


prompt 


proxy ftp-command 


put I oc a I - f i I e [r emot e- f i I e 


pwd 

quit 

quote ar gl ar g2... 

recv r emot e - f i I e [I oca I - f i I 

reget r emot e- f i I e [I ocal - f i 


remotehelp [c o mma n d - n a me] 

remotestatus [file-name] 

rename [from] [to] 
reset 

restart marker 
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put commands issued without a specified remote target filename. If arguments are 
specified, characters i n local filenames are translated during mget commands and get 
commands issued without a specified local target filename This command is useful 
when connecting to a non-UN IX remote computer with different file naming 
conventions or practices. Characters in a filename matching a character in i nchars 
are replaced with the corresponding character in out chars . If the character's position 
in i nchars is longer than the length of out chars, the character is deleted from the 
filename. 

Establish a connection to the specified host FTP server. An optional port number 
may be supplied, in which case, ftp will attempt to contact an FT P server at that 
port. If the auto-login option is on (default), ftp will also attempt to automatically 
log the user in to the FTP server (see below). 

T oggle interactive prompting. Interactive prompting occurs during multi pie file 
transfers to allow the user to selectively retrieve or store files. If prompting is turned 
off (default is on), any mget or mput will transfer all files, and any mdeiete will delete 
all files. 

Execute an ftp command on a secondary control connection. This command allows 
simultaneous connection to two remote FTP servers for transferring files between 
thetwo servers. The first proxy command should bean open, to establish the 
secondary control connection. Enter the command "proxy ?■ to see other ftp 
commands executable on the secondary connection. The following commands 
behave differently when prefaced by proxy :, open will not define new macros during 
the auto-login process, close will not erase existing macro definitions, get and mget 
transfer files from the host on the primary control connection to the host on the 
secondary control connection, and put, mput, and append transfer files from the host 
on the secondary control connection to the host on the primary control connection. 
T hird-party file transfers depend upon support of the FT P protocol pasv command 
by the server on the secondary control connection. 

1 Store a local file on the remote machine If remote-fi i e is left unspecified, the local 

filename is used after processing according to any ntrans or nmap settings in naming 
the remote file. File transfer uses the current settings for type, format, mode, and 
structure. 

Pri nt the name of the current worki ng di rectory on the remote machi ne. 

A synonym for bye. 

T he arguments specified are sent, verbati m, to the remote FT P server, 
e] A synonym forget. 

e ] Reget acts like get, except that if I ocal - f i I e exists and is smaller than remote-f i t e, 

i ocal -f i i e is presumed to be a partially transferred copy of remote-f i i e and the 
transfer iscontinued from theapparent point of failure. This command is useful 
when transferring very large fi les over networks that are prone to dropping 
connections. 

Request help from the remote FTP server. If acommand-name isspecified, it is supplied 
to the server as well. 

With no arguments, show status of remote machine. If f i i e- name isspecified, show 
status off i i e-name on remote machine. 

Rename thefile from on the remote machine, to thefile to. 

Clear reply queue. This command resynchronizes command/reply sequencing with 
the remote FTP server. Resynchronization may be necessary following a violation of 
the FT P protocol by the remote server. 

Restart the immediately following get or put at the indicated marker. On U NIX 
systems marker is usually a byte offset into thefile. 
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rmdir directory-name D elete a directory on the remote machine. 

runique Toggle storing of fileson thelocal system with uniquefilenames. If a file already 

exists with a name equal to the target local filename for a get or mget command, a .1 
is appended to the name. If the resulting name matches another existing file a .2 is 
appended to the original name. If this process continues up to . 99 , an error message 
is printed, and the transfer does not take place. The generated unique filename will 
be reported. N otethat runique will not affect local files generated from a shell 
command. T he default value is off. 


send I ocal • f i I e [remote-fi I e] 
sendport 


site argl arg2... 
size f i I e - name 


A synonym for put. 

T oggle the use of port commands. By default, ftp will attempt to use a port 
command when establishing a connection for each data transfer. The use of port 
commands can pra/ent delays when performing multiple file transfers. If the port 
command fails, ftp will usethedefault data port. W hen theuseof port commands is 
disabled, no attempt will be made to use port commands for each data transfer. This 
isuseful for certain FTP implementationswhich do ignore port commands but, 
incorrectly, indicate they've been accepted. 

The arguments specified are sent, verbatim, to the remote FTP server as a site 
command. 

Return size of file-name on remote machine. 


status 

struct [struct-name] 
sunique 


system 

tenex 

trace 

type [type - name ] 
umask [newmask] 

user user-name [password] [account] 


verbose 


Show the current status of ftp. 

Set the file transfer structure to struct-name. By default stream structure is used. 

Toggle storing of files on remote machine under uniquefilenames. Remote FT P 
server must support ftp protocol stou command for successful completion. The 
remote server will report unique name Default value is off. 

Show the type of operating system running on the remote machine 
Set the file transfer type to that needed to talk to TEN EX machines. 

Toggle packet tracing. 

Set the file transfer type to type-name. If notypeis sped f i ed, th e cu rrent type i s 
printed. T he default type is network ascii. 

Set the default umask on the remote server to newmask. If newmask is omitted, the 
current umask isprinted. 

Identify yourself to the remote FTP server. I f the password is not specified and the 
server requires it, ftp will prompt the user for it (after disabling local echo). If an 
account field is not specified, and the FTP server requires it, the user will be 
prompted for it. If an account field is specified, an account command will be relayed 
to the remote server after thelogin sequence is completed if the remote server did 
not require it for logging in. Unless ftp is invoked with auto-login disabled, this 
process is done automatically on initial connection to the FTP server. 

T oggle verbose mode. I n verbose mode, all responses from the FT P server are 
displayed to the user. In addition, if verbose is on, when a file transfer completes, 
statisti cs regardi ng the efficiency of the transfer are reported. By defau11, verbose is 
on. 


? [command ] 


A synonym for help. 


Command arguments which have embedded spaces may be quoted with quotation marks("). 


ABORTING A FILE TRANSFER 

T o abort a file transfer, use the terminal interrupt key (usually Ctrl-C). Sending transfers will be immediately halted. 
Receiving transfers will be halted by sending an FTP protocol abor command to the remote server, and discarding any 
further data received. The speed at which this is accomplished depends upon the remote server's support for abor processing. 
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If the remote server does not support the abor command, an ftp> prompt will not appear until the remote server has 
completed sending the requested file. 

The terminal interrupt key sequence will be ignored when ftp has completed any local processing and is awaiting a reply 
from the remote server. A long delay in this mode may result from the abor processing described earlier in this section, or 
from unexpected behavior by the remote server, including violations of the FTP protocol. If thedelay results from unex¬ 
pected remote server behavior, the local ftp program must be killed by hand. 

FILE NAMING CONVENTIONS 

Files specified as arguments to ftp commands are processed according to the following rules: 

If the filename - is specified, thestdm (for reading) or stdout (for writing) is used. 

If the first character of the filename is;, the remainder of the argument is interpreted as a shell command, ftp then forks a 
shell, using popen 3 with the argument supplied, and reads (writes) from the stdout (stdin). If the shell command includes 
spaces, the argument must be quoted; for example, is -it. A particularly useful example of this mechanism is dir more. 

Failing the preceding checks, if "globbing" isenabled, local filenames are expanded according to the rules used in thecsh 1; 
c.f. thegiob command. I f the ftp command expects a single local file (for example put), only the first filenamegenerated by 
the "globbing" operation is used. 

For mget commandsand get commands with unspecified local filenames, the local filename isthe remote filename, which 
may be altered by acase, ntrans, ornmap setting. The resulting filename may then be altered ifrunique ison. 

Formput commandsand put commands with unspecified remote filenames, the remote filename isthe local filename, which 
may be altered by an ntrans or nmap setting. The resulting filename may then be altered by the remote server if sunique ison. 

FILE TRANSFER PARAMETERS 

The FTP specification specifies many parameters that may affect a file transfer. The type may be one of ASCII, image 
(binary), ebcdic, and local byte size (for PD P N s-lOsand PDP N s-20s mostly), ftp supports the ASCI I and image types of 
fi le transfer, plus local byte size 8 for tenex mode transfers. 

ftp supports only the default values for the remaining filetransfer parameters: mode, form, and struct. 


THE.netrc FILE 


Thefilecontains login and initialization information used by the auto-login process. It resides in the user's home directory. 
The following tokens are recognized; they may be separated by spaces, tabs, or newlines: 


machine name 


default 


login name 


password st ri ng 


account st ri ng 


Identify a remote machine name. The auto-login process searches the file for a machine token that 
matches the remote machine specified on theftp command lineor as an open command argument. 
When a match is made, the subsequent tokens are processed, stopping when the end of file is 
reached or another machine or a default token is encountered. 

This isthe same as machine name except that default matches any name. T here can be only one 
default token, and it must be after all machine tokens. This is normally used asdef aui t login 
anonymous password user @si t e, thereby giving the user automatic anonymous ftp login to machines 
not specified. This can be overridden by using the -n flag to disable auto-login. 

Identify a user on the remote machine Ifthistoken is present, the auto-login process will initiatea 
login using the specified name. 

Supply a password. Ifthistoken is present, the auto-login process will supply the specified string if 
the remote server requires a password as part of the login process. N otethat ifthistoken is present 
in the file for any user other than anonymous, ftp will abort the auto-login process if the is readable 
by anyone besides the user. 

Supply an additional account password. Ifthistoken ispresent, theauto-login process will supply 
the specified string if the remote server requires an additional account password, or the auto-login 
process will initiate an acct command ifit does not. 
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macdef name D efi ne a macro. T his token functions like the ftp macdet command functions. A macro is defined 

with the specified name; its contents begin with the next line and continue until a null line 
(consecutive newline characters) is encountered. If amacro named init isdefined, it is automati¬ 
cally executed asthelast step in theauto-login process. 

ENVIRONMENT 

ftp utilizesthefollowing environment variables: 

home For default location of a file, if one exists 

shell For default shell 

SEE ALSO 

ftpd(8) 

HISTORY 

The ftp command appeared in BSD 4.2. 

BUGS 

C orrect execution of many commands depends upon proper behavior by the remote server. 

An error in the treatment of carriage returns in the BSD 4.2 ASCII-mode transfer code has been corrected. This correction 
may result in incorrect transfers of binary files to and from BSD 4.2 servers using the ASCI I type. Avoid this problem by 
using the binary image type 

BSD 4.2, 30 July 1991 

fuser 

fuser— Identify processes using files 

SYNOPSIS 

fuser [-a | -s ] [-si g n a I ][-kmuv] filename ... [ - ] [-si g n a I ] [-kmuv ] filename ... 
fuser [-1] 

DESCRIPTION 

fuser displays the PID s of processes usi ng the specified fi les or fi le systems. I n the default display mode, each fi lename is 
followed by a letter denoting the type of access: 

c Current directory, 

e Executable being run. 

f Open file f isomitted in default display mode, 

r Root directory, 

m mmap'ed file or shared library. 

fuser returns a nonzero return code if none of the specified files is accessed or in case of a fatal error. If at least one access has 
been found, fuser returns zero. 

OPTIONS 

-a Show all files specified on the command line. By default, only files that are accessed by at least one process 

are shown. 

-k Kill processes accessing thefile Unless changed with -signal, sigkill is sent. A fuser process na/er kills 

itself, but may kill other fuser processes. 




u 

-m 

-s 

-si gnal 

-u 

-V 

FILES 

/proc Location of the proc file system 

EXAMPLES 

fuser -km /home kills all processes accessi ng thefile system /home in any way. 

In thisexample: 

if fuser -s / dev /ttySI; then else something 

fi invokes something if no other process is using /dev/ttysi. 

RESTRICTIONS 

Processes accessing the same file or filesystem several timesin thesameway are only shown once. 

AUTHOR 

Werner A Imesberger (<aimesber@di.epfi.ch>u) 

SEE ALSO 

kill(l), killall(l), ps(l), kill(2) 

Linux, 11 October 1994 

9 ++ 

g++-GNU project C++Compiler 

SYNOPSIS 

g++ [ option j f i I ename ]. .. 

DESCRIPTION 

TheC and C++compilers are integrated; g++ isascriptto call gcc with options to recognizeC++. gcc processes in put files 
through one or more of four stages: preprocessing, compilation, assembly, and linking. This man page contains full 
descriptions for only C ++ specific aspects of the compiler, though it also contains summaries of some general-purpose 
options. For a fuller explanation of the compiler, see gcc(l). 

C ++source files use one of the suffi xes .c, .cc, .cxx, .cpp, or .c++; preprocessed C++ files usethesuffix .u. 

OPTIONS 

There are many command-line options, including options to control details of optimization, warnings, and codegeneration, 
which are common to both gcc and g++. For full information on all options, see gcc(l). 


List all known signal names. 

fi i ename specifies a file on a mounted filesystem or a block device that is mounted. All processes accessi ng 
files on that filesystem are listed. If a directory file is specified, it is automatically changed to filename/, to 
use any file system that might bemounted on that directory. 

Silent operation, -a, -u, and -v are ignored in this mode. 

Use the specified signal instead of sigkill when killing processes. Signalscan be specified either by name 
(for example, -hup) or by number (for example, -i). 

Append the username of the process owner to each PI D. 

Verbose mode. Processes are shown in a ps-like style. The fields pid, user, and command are similar to ps. 
access shows how the process accesses thefile. 

Reset all options and set the signal back to sigkill. 
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Options must be separate -dr is quite different from -d -r. 


M ost-f and -w options have two contrary forms: -fname and -fno-name (or-wname and -wno-name). Only the nondefault 
forms are shown here. 


-C 

-Dma c r o 
-Dma c r o =d e f n 
-E 


-fall-virtual 


-fdollars-in-identifiers 


-felide-constructors 


-fenum-int-equiv 


-fexternal-templates 


-fno-gnu-linker 


-fmemoize-lookups-fsave-memorized 


Compileor assemble the source files, but do not link. Thecompiler output isan 
object file corresponding to each source file. 

Define macro macro with the string i as its definition. 

Define macro macro as d e f n . 

Stop after the preprocessing stage; do not run thecompiler proper. The output is 
preprocessed source code, which is sent to the standard output. 

Treat all possiblememberfunctionsas virtual, implicitly. All member functions 
(except for constructor functions and new or delete member operators) are treated as 
virtual functions of the class where they appear. 

This does not mean that all callsto these member functionswi II be made through 
theinternal table of virtual functions. U nder somecircumstances, thecompiler can 
determine that a call to agiven virtual function can be made directly; in these cases 
the calls are direct in any case. 

Permit the use of $ in identifiers. T raditional C allowed the character $ to form part 
of identifiers; by default, GNU C also allows this. H owever, AN SI C forbids $ in 
identifiers, and GN U C++also forbids it by default on most platforms (though on 
some platforms it's enabled by default for GNU C++as well). 

Usethisoption to instruct the compiler to be smarter about when itcan elide 
constructors. Without thisflag, GNU C++and cfront both generate effectively the 
samecodefor 

A too (); 

A x (too ()); // x initialized by 'too ()', no ctor called 
A y = too (); // call to 'too ()' heads to temporary, // y is initial¬ 
ized from the temporary. 

N ote the difference. With thisflag, GNU C++initializesy directly from the call to 
food without going through atemporary. 

NormallyGNU C++allows conversion ofenumtoint, but not the other way 
around. Usethisoption if you want GN U C++to allow conversion of int to enum as 
well. 

Produce smaller code for template declarations by generating only a single copy of 
each template function where it is defined. T o usethisoption successfully, you must 
also mark all files that use templates with either #pragma implementation (the 
definition) or #pragma interface (declarations). 

When your code is compiled with -fexternai-tempiates, all template instantiations 
are external. You must arrange for all necessary instantiationsto appear in the 
implementation file; you can do thiswith a typedef that references each instantiation 
needed. Conversely, when you compile using the default option -fno- external- 
templates, all template instantiations are explicitly i nternal. 

Do not output global initializations (such as C++constructors and destructors) in 
the form used bytheGNU linker (on systems where the GN U linker is the standard 
method of handling them). Usethisoption when you want to use a non-GN U 
linker, which also requires using the coiiect 2 program to make sure the system 
linker includes constructors and destructors (coiiect 2 isincluded i n the GNU CC 
distribution.) For systems which must use coiiect 2 , thecompiler driver gcc is 
configured to do this automatically. 

These flags are used to get the compiler to compile programs faster using heuristics 
T hey are not on by default since they are only effective about half the time. T he 
other half of the ti me programs compi le more slowly (and take more memory). 



-fno-default-inline 


-fno-strict-prototype 


-fhandle-signatures- 
fno-handle-signatures 
-fthis-is-variable 


g++ 



The first time the compiler must build a call to a member function (or reference to a 
data member), it must (1) determinewhether theclass implements member 
functions of that name; (2) resolve which member function to call (which involves 
figuring out what sorts of type conversions need to be made); and (3) check the 
visibility of the member function to the caller. All of this adds up to slower 
compilation. N ormally, the second time a call is made to that member function (or 
reference to that data member), it must go through the same lengthy process again. 
This means that code I ike this: 

cout « "This " « p « "has"« n « " legs.\n"; 
makes six passes through all three steps. By using a software cache, a "hit” signifi¬ 
cantly reduces this cost. U nfortunately, using the cache introduces another layer of 
mechanisms which must be implemented, and so incurs its own overhead. - 
f memorize- lookups enables the software cache. 

Because access privileges (visibility) to members and member functions may differ 
from one function context to the next, g++ may need to flush the cache. With the - 
fmemoize-iookups flag, the cache is flushed after every function that is compiled. The 
-fsave-memorized flag enables the same software cache, but when the compiler 
determines that the context of the last function compiled would yield the same 
access privileges of the next function to compile, it preserves the cache. This is most 
helpful when defining many member functions for the same class: with the 
exception of member functions which are friends of other classes, each member 
function has exactly the same access privileges as every other, and the cache need not 
be flushed. 

Do not make member functions inline by default merely because they are defined 
inside the class scope. Otherwise, when you specify-o, member functions defined 
inside class scope are compiled inline by default; that is, you don't need to add 
inline in front of the member function name. 

Consider the declaration int too; (). In C++, this means that the function too takes 
no arguments. In AN SI C, this is declared int too (void);. W ith the flag -fno- 
strict-prototype, declaring functions with no arguments is equivalent to declaring 
its argument list to be untyped, that is int foo(); is equivalent to saying int too 
(...);. -tnonnuii-obj ects. Normally, GNU C-H-makes conservative assumptions 
about objects reached through references. For example the compiler must check that 
aisnotnull in code like the followi ng: 

obj &a = g (); 
a.f (2); 

C hecking that references of this sort have non-null values requires extra code, 
however, and it is unnecessary for many programs. You can use -tnonnuii-obj ects to 
omit the checks for null, if your program doesn't require the default checking. 

These options control the recognition of the signature and sigot constructs for 
specifying abstract types. By default, these constructs are not recognized. 

The incorporation of user-defined free store management into C++has made 
assignment to this an anachronism. Therefore, by default GNU C++treats the type 
ofthisin a member function of classX to bex ‘const. In other words itisillegal to 
assign to thiswithin a class member function. However, for backwards compatibil¬ 
ity, you can invoketheold behavior by using -fthis-is-variabie. 

Produce debugging information in the operati ng system's native format (for D BX or 
SDB or DWARF). GDB also can work with this debugging information. On most 
systems that useD BX format, -g enables use of extra debugging information that 
only GDB can use. 

Unlike most other C compilers, GN U CC allows you to use-g with - 0 . The 
shortcuts taken by optimized code may occasionally produce surprising results: some 
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-Idi r 
-Ldi r 
-II i brary 

-nostdinc 

-nostdinc++ 

-0 

-o file 
-S 

-traditional 


-Uma c r o 
-Wall 

-Wenum-clash 

-Woverloaded- 


variables you declared may not exist at all; flow of control may briefly move where 
you did not expect it; some statements may not be executed because they compute 
constant results or their values were already at hand; some statements may execute in 
different places because they were moved out of loops. 

N evertheless, it proves possible to debug optimized output. This makes it reasonable 
to use the optimizer for programs that might have bugs. 

Append di rectory di r to the list of directories searched for include files. 

Add directory di r to the list of di rectories to be searched for-i. 

Use the library named i i brary when linking. (C++programs often require -ig++ for 
successful linking.) 

Do not search the standard system directories for header files. Only the directories 
you have specified with -i options (and the current directory, if appropriate) are 
searched. 

Do not search for header filesin thestandard directories specific to C++, but do still 
search theother standard directories. (Thisoption isused when building iibg++.) 
Optimize. Optimizing compilation takes somewhat more time, and a lot more 
memory for a large function. 

Place output in filet i i e. 

Stop after the stage of compilation proper; do not assemble. The output is an 
assembler code file for each nonassembler input file specified. 

Attempt to support some aspects of traditional C compilers. Specifically, for both C 
and C++programs: 

In the preprocessor, comments convert to nothing at all, rather than to aspace. This 
allows traditional token concatenation. 

In the preprocessor, macro arguments are recognized within string constants in a 
macro definition (and their values arestringified, though without additional quote 
marks, when they appear in such a context). The preprocessor always considers a 
string constant to end at a newline. 

The preprocessor does not predefi ne the macro stdc when you use -traditional, but 
still predefi nesGNUc (sincetheGN U extensions indicated byGNuc are not affected by 
-traditional). If you need to write header files that work differently depending on 
whether -traditional isin use, bytesting both of these predefined macros you can 
distinguish four situations: GNU C, traditional GN U C, other AN SI C compilers, 
and other old C compilers. 

In the preprocessor, comments convert to nothing at all, rather than to aspace. This 
allows traditional token concatenation. 

String "constants" are not necessarily constant; they are stored in writable space, and 
identical looking constants are allocated separately. For C ++ programs only (not C), 
-traditional has one additional effect: assignmentto this is permitted. Thisisthe 
Same as the effect Of -fthis-is-variable. 

Undefine macro macro. 

Issue warnings for conditions that pertain to usage that we recommend avoiding and 
that we believe is easy to avoid, a/en in conjunction with macros. 

W am when converting between different enumeration types, 
virtual In a derived class, the definitions of virtual functions must match the type signature 

of a virtual function declared in thebase class. Use thisoption to request warnings 
when a derived class declares a function that may bean erroneous attempt to define 
a virtual function; that is, warn when a function with thesame name as a virtual 
function in thebase class, but with a type signature that doesn't match any vi rtual 
functionsfromthebasecl ass. 
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-Wtemplate-debugging 

When using templates in a C++program, warn if debugging is not yet fully 
available. 

-w 

Inhibit all warning messages. 

+eN 

Control how virtual function definitions are used, in a fashion compatible with 
cfront 1.x. 

PRAGMAS 

T wo #pragma directives are supported for GN U C++, to permit using the same header file for two purposes: as a definition of 

interfaces to agiven object class, and as the full definition of the contents of that object class. 

#pragma interface 

Use this directive in header files that defineobject classes, to savespacein most of 
the object files that use those classes. Normally, local copies of certain information 
(backup copies of inline member functions, debugging information, and the internal 
tables that implement virtual functions) must be kept in each object file that 
includes class definitions. You can use this pragma to avoid such duplication. When 
a header file containing #pnagma interface is included in a compilation, this auxiliary 
information will not be generated (unless the main input sourcefile itself uses 
#pragma implementation). Instead, the object files will contain references to be 
resolved at link time. 

#pragma implementation 

U sethis pragma in a main input file, when you want full output from included 

#pragma implementation lobjects.h! 

header files to be generated (and made globally visible). The included header file, in 
turn, should use#pragma interface. Backup copies of inline member functions, 
debugging information, and the internal tables used to implement virtual functions 
are all generated in implementation files. 

If you use#pragma implementation with no argument, it applies to an include file 
with thesamebasenameas your source file; for example, in aiiciass.cc, #pragma 
implementation by itself is equivalent to #pragma implementation "allclass.h". Use 
the string argument if you want a single implementation file to include code from 
multiple header files. 

There is no way to split up the contents of a single header file into multiple 
implementation files. 

FILES 

file.h 

C header (preprocessor) file 

file.i 

Preprocessed C source 

file file.C 

C++source fi le 

file.cc 

C++source fi le 

file.cxx 

C++source file 

file.s 

Assembly language file 

file.o 

Object file 

a.out 

Link edited output 

TMPDIR/cc 

T emporary files 

LIBDIR/cpp 

Preprocessor 

LIBDIR/ccIplus 

Compiler 

LIBDIR/collect 

Linker front end needed on some machines 

LIBDIR/libgcc.a 

GCC subroutine library 

/lib/crt[01n] .0 

Start-up routine 

LIBDIR/ccrt0 

Additional start-up routinefor C ++ 

/lib/libc.a 

Standard C library; seeintro(3) 
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/usr/inciude Standard directory for #inciude files 

LiBDiR/inciude Standard gcc directory for #inciude files 

LiBDiR/g++-inciude Additional g++ di rectory for #inciude 

LIBDIR is usually /usr/local/lib/machine/version. 

tmpdir comes from the environment variable tmpdir (default /usr/tmp ifavailable, else /tmp). 

SEE ALSO 

gcc(l), cpp(l), as(l), ld(l), gdb(l), adb(l), dbx(l), sdb(l), gcc, cpp, as, Id, and gdb entries in info. 

Using and Porting GNU CC (for version 2.0), Richard M . Stallman; TheC Preprocessor, Richard M . Stallman; Debugging 
with GDB: theGNU Source-Le/el Debugger, Richard M . Stallman and Roland H. Pesch; Usngas theGNU Assembler, Dean 
Eisner, Jay Fenlason and friends; gld: theGNU linker, Steve Chamberlain and Roland Pesch. 

BUGS 

For i nstructions on howto report bugs, seetheGCC manual. 

COPYING 

Copyright © 1991,1992,1993 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim 
copies of this manual provided the copyright notice and this permission notice are preserved on all copies. 

Permission isgranted to copy and distribute modified versionsof thismanual under the conditions for verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 

Permission isgranted to copy and distribute translations of thismanual into another language, under the above conditions 
for modified versions, except that this permission notice may be included in translations approved by the Free Software 
Foundation instead of in the original English. 

AUTHORS 

See the GNU CC Manual for the contributors to GNU CC. 

GNU Tools, 30 April 1993 

g3topbm 

g3topbm— C onvert a G roup 3 fax file into a portable bitmap 

SYNOPSIS 

g3topbm [-kludge][-reversebits][-stretch][g3f i I e] 

DESCRIPTION 

Reads a Group 3 fax file as input. Produces a portable bitmap as output. 

OPTIONS 

-kludge T el Is g3topbm to ignore the first few lines of the file; sometimes fax files have some junk at the beginning, 

-reversebits T el Is g3topbm to interpret bits least-significant first, instead Of the default most-significant first. 

Apparently, some fax modems do it oneway and others do it the other way. If you get a whole bunch of 
"bad codeword" messages, try using this flag. 

-stretch T el Is g3topbm to stretch the image vertically by duplicating each row. This is for the low-quality transmis¬ 

sion mode. 


All flags can be abbreviated to their shortest unique prefix. 



gawk 


161 


REFERENCES 

The standard for Group 3 fax is defined in CCITT Recommendation T.4. 

BUGS 

Probably. 

SEE ALSO 

pbmtog3(l), pbm(5) 

AUTHOR 

Copyright© 1989 by Paul Haeberli (paui@manray.sgi.com) 

2 October 1989 

gawk 

gawk— Pattern scanning and processing language 

SYNOPSIS 

gawk [ POSIX or GNU style options ] -f program-file [ — ] file ... 
gawk [ POSIX or GNU style options ] [ -- ] program-text file ... 

DESCRIPTION 

gawk is the GNU Project's implementation of theawk programming language. It conforms to the definition of the language 
in the 1003.2 Command Language and Utiliti es Standard. This version in turn is based on the description in TheAWK 
Programming Language, by Aho, Kernighan, and Weinberger, with the additional features defined in the System V Release 4 
version of awk. gawk also provides some GN U-specific extensions. 

The command line consists of options to gawk itself, theawk program text (if not supplied via the-f or--tile options), and 
values to be made available in theARGc and argv predefined awk variables. 

OPTIONS 

gawk options may be either the traditional one-letter options, or theGN U-style long options. T raditional style options start 
with a single-, while GN U long options start with —. GNU -style long options are provided for both GNU -speci fi c featu res 
and for mandated features. Other implementations of theawk language are likely to only accept the traditional one-letter 
options 

Following the standard, gawk-specific options are supplied via arguments to the -w option. M ultiple-w options may be 
supplied, or multiple arguments may be supplied together if they are separated by commas, or enclosed in quotes and 
separated by whitespace. Caseisignored in arguments to the -w option. Each -w option has a correspond! ngGN U -style long 
option, as detailed below. Arguments to GNU -style long options are either joined with the option by an = sign, with no 
intervening spaces, or they may be provided in the next command-line argument. 

gawk accepts the following options: 

-f f s, —fieid-separator=f s Usefs for the input field separator (the value of the Fs-predefined variable). 

-v v a r =v a i, —assign=var=vai Assign the value va i , to the variable v a r , before execution of the program begins. Such 

variable values are available to the begin block of an awk program. 

-f program-f i i e, Read theawk program source from the fi le pr ogr a m- f i i e, instead of from the first 

—fiie=pr ogr am- f i 1 0 command-li ne argument. M ultiple-f (or —file) options may be used. 

-mf=NNN, -mr=NNN Set various memory limits to the value nnn. The t flag sets the maxi mum number of fields, 

and the r flag sets the maximum record size. T hesetwo flags and the -m option are from the 
AT&T Bell Labs research version of awk. They are ignored by gawk, si nee gawk has no 
predefined limits. 
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-W compat, —compat 


-W copyleft, -W copyright, 
—copyleft, —copyright 
-W help, -W usage 
—help, —usage 
-W lint, --lint 

-W posix, —posix 


-W source=pr ogr am-1 ext, 
—source=pr ogr am-1 ext 


-W version, --version 


Run in compatibility mode. In compatibility mode gawk behaves identically to awk; noneof 
the G N U -specific extensionsare recognized. See "G N U Extensions,'' later in this manual 
page, for more information. 

Print the short version of theGN U copyright information message on the error output. 

Print a relatively short summary of the available options on the error output. Per the G N U 
Coding Standards, these options cause an immediate, successful exit. 

Provide warnings about constructs that are dubious or nonportable to other awk implemen¬ 
tations. 

This turns on compatibility mode, with the following additional restrictions^ escape 
sequences are not recognized. 

The synonym tunc for the keyword function is not recognized. 

The operators** and **= cannot beused in placeof ■ and 

Use program-text asawk program source code. This option allows the easy intermixing of 
library functions (used via the-t and —tile options) with source code entered on the 
command line. It is intended primarily for medium to large awk programs used in shell 
scripts. 

The-w source= form of this option uses the rest of the command-line argument for 
program-text ; no other options to -wwill be recognized in the same argument. 

Print version information for this particular copy of gawk on the error output. This is useful 
mainly for knowing if the current copy of gawk on your system is up-to-date with respect to 
whatever theFreeSoftwareFoundation is distributing. PertheGNU Coding Standards, 
these options cause an immediate, successful exit. 

Signal the end of options. This is useful to allow further arguments to the awk program itself 
to start with a-. This is mainly for consistency with the argument-parsing convention used 
by most other programs. 


In compatibility mode, any other options are flagged as illegal, but are otherwise ignored. In normal operation, aslongas 
program text has been supplied, unknown options are passed on to the awk program in theARGv array for processing. This is 
particularly useful for running awk programs via the#! executable interpreter mechanism. 


awk PROGRAM EXECUTION 

An awk program consists of a sequence of pattern-action statements and optional function definitions: 

pattern { action state me nt s } 

function n a me (p a r a me t e r list) { s t a t e me n t s } 

gawk first reads the program source from the program-file(s) if specified, from arguments to -w sources or from the first 
nonoption argument on thecommand line. The-t and -w source= options may beused multi pie ti mes on thecommand 
line gawk will read the program text as if all the program-files and command-line source texts had been concatenated 
together. This is useful for building libraries of awk functions, without having to include them in each new awk program that 
uses them. It also provides the ability to mix library functionswith command-line programs. 

T he environment variable awkpath specifies a search path to use when finding source files named with the-f option. If this 
variable does not exist, the default path is . :/usr/lib/awk:/usr/local/lib/awk. 

If a filename given to the -f option contains a / character, no path search is performed. 

gawk executes awk programs in the following order. First, all variable assignments specified via the -v option are performed. 

N ext, gawk compiles the program into an internal form. Then, gawk executes the code in the begin block(s) (if any), and then 
proceeds to read each file named in theARGv array. If there are no files named on thecommand line, gawk reads the standard 
input. 

If a filename on thecommand line has the form va r =va i , it istreated as a variable assignment. T he variable va r will be 
assigned the value v a i . (This happens after any begin block(s) have been run.) Command-linevariableassignment ismost 
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useful for dynamically assigning values to thevariablesawk uses to control how input is broken into fields and records. It is 
also useful for controlling state if multiple passes are needed over a single data file. 

If the value of a particular element of argv is empty gawk skips over it. 

For each line in the input, gawk tests to see if it matches any pattern in theawk program. For each pattern that the line 
matches, the associated action is executed. The patterns are tested in the order they occur in the program. 

Finally, after all theinput isexhausted, gawk executes the code in the end block(s) (if any). 

VARIABLES AND FIELDS 

awk variables are dynamic; they come into existence when they are first used. T heir values are either floating-point numbers 
or strings, or both, depending upon how theyareused. awk also has one-dimensional arrays; arrays with multipledimensions 
may be simulated. Several predefined variables are set as a program runs; these will be described as needed and summarized 
in the "Built-In Variables" subsection. 


FIELDS 

As each input line is read, gawk splits the line into fields, usi ng the value of the fs variable as the field separator. If fs is a 
single character, fields are separated by that character. Otherwise, fs is expected to be a full regular expression. In the special 
case that fs is a single blank, fields are separated by runs of blanks or tabs. N ote that the value of ignorecase (seethe 
following) will also affect how fields are split when fs is a regular expression. 

If the fieldwidths variable isset to a space separated list of numbers, each field is expected to have fixed width, and gawk will 
split up the record using the specified widths. The value of fs is ignored. Assigning a new value to fs overrides the use of 
fieldwidths, and restores the default behavior. 

Each field in theinput line may dereferenced by its position, $ 1 , $ 2 , and so on. $0 isthewhole line The value of afield may 
be assigned to as well. Fields need not be referenced by constants: 

n =5 

print $n 

prints the fifth field in theinput line. The variable nf is set to the total number of fields in theinput line. 

References to nonexistent fields (that is, fields after $nf) produce the null-string. FI owever, assigning to a nonexistent field 
(for example, $(nf+ 2 ) = 5 ) will increase the value of nf, create any intervening fields with the null string as their value, and 
cause the value of $0 to be recomputed, with the fields being separated by the value of ofs. References to negative-numbered 
fieldscauseafatal error. 


BUILT-IN VARIABLES 


awk's built-in variables are the following: 


ARGO 

ARGIND 

ARGV 

CONVFMT 

ENVIRON 


ERRNO 

FIELDWIDTHS 


The number of command-line arguments (does not include options to gawk, or the program source). 

T he index in argv of the current file bei ng processed. 

Array of command-linearguments. Thearray isindexed from 0 to argc - 1 . Dynamically changing the 
contents of argv can control the fi les used for data. 

The conversion format for numbers, "%.6g", by default. 

An array containing the values of the current environment. Thearray isindexed by the environment 
variables, each element being the value of that variable (for example, environ; "home n ] might be/u/arnoid). 
C hanging this array does not affect the environment seen by programs which gawk spawns via redirection 
orthesystemo function. (Thismay change in a future version of gawk.) 

If a system error occurs either doing a redirection forgetiine, during a read for getiine, or during a 
closed, then errno will contain astring describing the error. 

A whitespace-separated list of fieldwidths. When set, gawk parses the input into fields of fixed width, 
instead of using the value of theFs variable as the field separator. The fixed field width facility isstill 
experimental; expect the semantics to change as gawk evolves overtime. 
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FILENAME 

FNR 
FS 

IGNORECASE 


NF 

NR 

OFMT 

OFS 

ORS 

RS 


RSTART 
RLENGTH 
SUBSEP 

ARRAYS 

Arrays are subscripted with an expression between square brackets. If the expression is an expression list (ex p r, ex p r ...) 
then the array subscript is a string con si sting of the con catenation of the (string) value of each expression, separated by the 
value of the subsep variable. Thisfacility is used to simulate multiply dimensioned arrays. For example, 

i = "A" ; j = "B" ; k = "C" 
x[i, j, k] = "hello, world\n" 

assigns the string hello, worid\n to the element of the array x which is indexed by the string ■a\034b\034C". All arrays in awk 
are associative, that isindexed by string values. 

The special operator in may be used in an if or while statement to seif an array has an index consisting of a particular 
value: 

if (val in array) 
print array[val] 

If the array has multiple subscripts, use (i, j )in array. 

The in construct may also be used in a for loop to iterate over all the elements of an array. 

An element may be deleted from an array using the delete statement. The delete statement may also be usd to delete the 
entire contents of an array. 

VARIABLETYPING AND CONVERSION 

Variables and fields may be floating-point numbers, or strings, or both. H ow the value of a variable is interpreted depends 
upon its context. If used in a numeric expression, it will be treated as a number; if used as a string, it will be treated as a 
string. 

T o force a variable to be treated as a number, add 0 to it; to force it to be treated as a string, concatenate it with the null 
string. 


The name of the current input file If no files are specified on the command line, the value of filename is-. 
H owever, filename is undefined inside the begin block. 

T he input record number in the current input file. 

The input field separator, a blank by default. 

Controls the case-sensitivity of all regular expression operations. If ignorecase has a nonzero value, then 
pattern matching in rules, field splitting with fs, regular expression matching with ' and r, and the 
gsub(), indexf), match(), spiitf ),and sub( ) predefined functionswill all ignore case when doing regular 
expression operations. Thus, if ignorecase isnot equal to zero, /aB/ matches all of the strings ab, aB, Ab, 
and ab. As with all awk variables, the initial value of ignorecase is zero, so all regular expression operations 
are normally case-sensitive. 

The number of fields in the current input record. 

The total number of input records seen so far. 

The output format for numbers, "%.6g", by default. 

The output field separator, a blank by default. 

The output record separator, by default a newline. 

The input record separator, by default a newline, rs is exceptional in that only the first character of its 
string value is used for separating records. (This will probably change in a future release of gawk.) If rs is set 
to the null string, then records are separated by blank lines. W hen rs is set to the null string, then the 
newline character always acts as a field separator, in addition to whatever value fs may have. 

The index of the first character matched by match(); 0 if no match. 

Thelength of the string matched bymatch(); -1 if no match. 

The character used to separate multiple subscripts in array elements, by default n034. 
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When a string must be converted to a number, the conversion is accomplished using atot (3). A number is converted to a 
string by using the value of convfmt as a format string for sprintf(3), with the numeric value of the variable as the argument. 

H owever, even though all numbers in awk are floating-point, integral values are always converted as integers. Thus, given this: 

CONVFMT = "%2.2f" 
a =12 
b =a"" 

the variable b has a string value of 12 and not 12 . 00 . 

gawk performs comparisons as follows: If two variables are numeric, the/ are compared numerically. If one value is numeric 
and the other has a string value that is a "numeric string," then comparisons are also done numerically. Otherwise, the 
numeric value isconverted to a string and a string comparison is performed. T wo strings are compared, of course, as strings. 
According to the standard, even if two strings are numeric strings, a numeric comparison is performed. H owever, this is 
clearly incorrect, and gawk does not do this 

Uninitialized variables have the numeric value 0 and the string value ■■ (the null, or empty, string). 

PATTERN SAND ACTIO N S 

awk is a line-oriented language. The pattern comes first, and then the action. Action statements are enclosed in and .br. 

Either the pattern may be missing, or the action may be missing, but, of course, not both. If the pattern is missing, the action 
will be executed for every single line of input. A missing action is equivalent to 
{ print } 

which prints theentire line. 

Comments begin with the# character, and continue until the end of the line. Blank lines may be used to separate state¬ 
ments. N ormally, a statement ends with a newline however, this is not the case for linesending in a,, {, ?, or 11 . Lines 
ending in do or else also have their statements automatically continued on the following line. In other cases, a line can be 
continued by ending it with a \, in which case the newline will be ignored. 

M ultiple statements may be put on one line by separating them with a semicolon. This applies to both the statements within 
the action part of a pattern-action pair (the usual case), and to the pattern-action statements themselves. 

PATTERNS 

awk patterns may be one of the following: 

BEGIN 

END 

/regul ar expressi on/ 
relational expression 
pattern && p a 11 e r n 
pattern jj pattern 
pattern ? pattern : pattern 
(pattern) 

! pattern 

pat t er n 1, pat t er n2 

begin and end are two special kinds of patterns that are not tested against the input. The action parts of all begin patterns are 
merged as if all the statements had been written in a single begin block. They are executed before any of the input is read. 
Similarly, all the end blocks are merged, and executed when all the input is exhausted (or when an exit statement is 
executed), begin and end patterns cannot be combined with other patterns in pattern expressions, begin and end patterns 
cannot have missing action parts 

For /regul ar expressi on / patterns, the associated statement is executed for each input line that matches the regular 
expression. Regular expressionsarethesameasthosein egrep(l), and are summarized as follows: 
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A rei ati onai expression may use any of the operators defined later in the section on actions. These generally test whether 
certain fields match certain regular expressions. 

The&&, !|, and i operators are logical and, logical or, and logical not, respectively, as in C. They do short-circuit evaluation, 
also as in C, and are used for combining more primitive pattern expressions. As in most languages, parentheses may be used 
to change the order of evaluation. 

The?: operator is I ike the same operator in C. If the first pattern is true, then the pattern used fortesting is the second 
pattern; otherwise, it is the third. Only one of the second and third patterns is evaluated. 

T he pat t er n 1, pat t er n2 form of an expression is called a range pattern. It matches all input records starting with aline that 
matches p a11 er n 1 , and continuing until a record that matchespa 11 e r n2 , inclusive. It does not combine with any other sort of 
pattern expression. 

REGULAR EXPRESSIONS 

Regular expressions are the extended kind found in egrep. They are composed of characters as follows: 
c M atches the non-meta-character c. 

\ c M atches the literal character c. 

M atches any character except newline 
M atches the begi nning of a line or a string. 

$ M atches the end of a li ne or a string. 

[a be... ] Character class, matches any of the characters abc.... 

[ "a be... ] N egated character class, matches any character except abc.. . and newline 
r 1 jr 2 Alternation: matches either ri on 2. 

rlr 2 Concatenation: matchesri, and then r 2 . 

r + M atches one or more rs 

r* M atches zero or more rs. 

r? Matches zero or oners. 

(r) Grouping: matches r. 

The escape sequences that are valid in string constants are also legal in regular expressions. 

ACTIONS 

Action statements are enclosed in braces, { and >. Action statements consist of the usual assignment, conditional, and looping 
statements found in most languages. Theoperators, control statements, and input/output statements available are patterned 
after those in C. 


OPERATORS 


The operators in awk, in order of increasing precedence, are 



&& 


< >, <=>= 
blank 


Assignment. Both absolute assignment (var = vai ue) and operator-assignment (the other forms) are 
supported. 

TheC conditional expression. T his has the form ex pr l ? expr 2 : expr 3 .If expri istrue, thevalueof the 
expression isexpr 2 ; otherwise, it isexpr 3 .0 nly one of expr 2 and expr 3 is evaluated. 

Logical or. 

Logical and. 

Regular expression match, negated match. N OTE: Do not use a constant regular expression (/fool) to the 
left of a • or r. Only use one on the right side. The expression /too/ 'exp has the same meaning as (($0 
' if 00 1 ) ' ex p) . T his is usually not what was intended. 

T he regular relational operators. 

String concatenation. 

Addition and subtraction. 
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*/% M ultiplication, division, and modulus. 

+-! U nary plus, unary minus, and logical negation. 

Exponentiation (** may also be used, and **= for the assignment operator). 

++ — Increment and decrement, both prefix and postfix. 

$ Field reference. 

CONTROL STATEMENTS 

The control statements are as follows: 

if (condition) statement [ else statement ] 
while (condition) statement 
do statement while (condition) 
for (exprl; expr2; expr3) statement 
for (var in array) statementbreak 
continue 

delete array[index] 
delete array 
exit [ expression ] 

{ statements } 

I/O STATEMENTS 

The i nput/output statements are as follows: 

close (f i i e n a me) C lose file (or pipe, see paragraph following this list), 

getiine Set $0 from next input record; set nf, nr, fnr. 

getiine <f i i e Set $0 from next record of f i i e; set nf. 

getiine var Set var from next input record; setNF, fnr. 

getiine var <f i i e Set var from next record of f i I e . 

next Stop processing the current input record. The next input record is read and processing starts 

over with the first pattern in theawk program. If the end of the input data isreached, the 
end block(s), if any, are executed. 

next file Stop processing the current input file. The next input record read comes from the next 

input file filename is updated, fnr i s reset to i, and processing starts over with thefirst 
pattern in theawk program. If the end of the input data isreached, the end block(s), if any, 
are executed. 

print Prints the current record. 

print expr-iist Prints expressions. Each expression isseparated by the value of the ofs variable. The output 

record is terminated with thevalueof theoRs variable 

print expr-iist >f i i e Prints expressions on f i i e . Each expression is separated by the value of the ofs variable T he 

output record is terminated with thevalueof theoRs variable 
printf f mt, expr-iist Format and print, 

printf fmt, expr-iist >f i i e Format and print on f i i e. 

systemfcmd-1 i ne) Execute the command c md-1 i ne, and return the exit status. (This may not be available on - 

POSIX systems.) 

Other input/output redirections are also allowed. For print and printf, »f i i e appends output to thef i i e , while | command 
writes on a pipe. In a similar fashion, command | getiine pipes into getiine. The getiine command will return 0 on end of 
file, and -1 on an error. 

THE printf STATEMENT 

Theawk versions of the printf statement and sprintf() function accept the following conversion specification formats: 

%c An ASCII character. If the argument used for %c is numeric, it is treated as a character and printed. 

Otherwise, the argument is assumed to beastring, and the only first character of that string is printed. 
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%d A decimal number (the integer part). 

%i Just like %d. 

%e A floating-pointnumberoftheform [-]d.ddddddE[+-]dd. 

%f A floating-pointnumberoftheform [-jddd.dddddd. 

%g Usee or f conversion, whichever is shorter, with nonsignificant zeros suppressed. 

%o An unsigned octal number (again, an integer). 

%s A character string. 

%x An unsigned hexadecimal number (an integer). 

%x Like%x, but using ABC DEF instead of abcdef. 

%% A single % character; no argument is converted. 

There are optional, additional parameters that may lie between the % and the control letter: 

Theexpression should be left-justified within itsfield. 

width The field should be padded to this width. If the number has a leading zero, then the field will be padded 

with zeros. Otherwise, it ispadded with blanks This applies a/en to the nonnumeric output formats. 

.prec A number indicating the maximum width of strings or digits to the right of the decimal point. 

T he dynamic wi dt h and prec capabilities of the C printtO routines are supported. A * i n place of either the wi dt h or p r ec 
specifications will cause their values to betaken from the argument list to printt or sprinttf). 

SPECIAL FILENAMES 

When doing I/O redirection from either print or printt into a file, or viagetiine from a file, gawk recognizes certain special 
filenames internally. These filenames allow access to open file descriptors inherited from gawk's parent process (usually the 
shell). Other special filenames provide access information about the running gawk process. The filenames are 

/dev/pid Reading thisfile returns the process ID of the current process, in decimal, terminated with a newline, 

/dev/ppid Reading thisfile returns the parent process ID of the current process, in decimal, terminated with a 

newline 

/dev/pgrpid Reading thisfile returns the process group ID of the current process, in decimal, terminated with a 
newline 

/dev/user Reading thisfile returns a single record terminated with a newline. The fields are separated with blanks $1 

is the value of the getuid(2) system call, $2 isthevalueof thegeteuid(2) system call, $3 isthevalueof the 
getgid(2) system call, and $4 isthevalueof thegetegid( 2) system call. If there are any additional fields, 
they are the group IDs returned by getgroups(2). M ultiple groups may not be supported on all systems, 
/dev/stdin T he standard input. 

/dev/stdout T he standard output. 

/dev/stderr The standard error output. 

/dev/td/n T he file associated with theopen fi le descriptor n . 

These are particularly useful for error messages. For example, you could use 
print "You blew it!" > "/dev/stderr" 
whereas you would otherwise have to use 
print "You blew it!" j "cat 1>&2" 

These filenamesmay also beused on thecommand lineto name data files. 

NUMERIC FUNCTIONS 

awk has thefollowing predefined arithmetic functions: 
atan 2 (y , *) Returns the arctangent ofy/x in radians, 
cos(ex p r ) Returns the cosine in radians. 
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exp(expr ) 
int(ex pr ) 
log (ex pr ) 
rand() 
sin(expr ) 
sqrt (expr ) 
snand(expr ) 


The exponential function. 

Truncatesto integer. 

The natural logarithm function. 

Returns a random number between 0 and 1. 

Returnsthesinein radians. 

The square root function. 

Useexpr as a new seed for the random number generator. If no ex pr is provided, the time of day will be 
used. The return value is the previous seed for the random number generator. 


STRING FUNCTIONS 


awk hasthefollowing predefined string functions: 


gsub(r , s, t ) 

index(s , t ) 
length(s ) 
match(s , r ) 

split (s , a, r) 

sprintf (f mt , expr -1 i s t ) 
sub(r , s , t ) 
substr(s, i , n) 
tolower(s t r) 

toupper(str) 


For each substring matching the regular expression r in the string t, substitute the strings, 
and return the number of substitutions. If t is not supplied, use$o. 

Returns the index of the stri ng t in thestring s ,or 0 if t isnot present. 

Returns the length of the string s , orthelength of $0 if s isnot supplied. 

Returns the position in s where the regular expression r occurs, or 0 if u isnot present, and 
sets the values of rstart and rlength. 

Splitsthestrings into thearray a on the regular expression r , and returnsthe number of 
fields. If r isomitted, fs is used instead. Thearray a is cl eared first. 

Prints expr- 1 i st according to fmt , and returns the resulting string. 

J ust like gsub(), but only the first matching substring is replaced. 

Returns then-character substring of s starting at i. If n is omitted, the rest of s isused. 
Returns a copy of the string s t r , with all the uppercase characters in str translated to their 
corresponding lowercase counterparts. N onalphabetic characters are left unchanged. 
Returns a copy of the string str, with al I the lowercase characters i n s t r translated to thei r 
corresponding uppercase counterparts. N onalphabetic characters are left unchanged. 


TIME FUNCTIONS 

Since one of the primary uses of awk programs is processing log files that contain timestamp information, gawk provides the 

following two functions for obtaining time stamps and formatting them. 

systimeo Returns the current time of day as the number of seconds since the Epoch (M idnight UTC, 

January 1,1970 on systems). 

strftime(f or mat, t i mes t a mp ) Formats t i meat a mp accordi ng to the specification in t or mat . T he t i mes t amp should be of the 
same form as returned by systimeo. If t i meat amp is missing, the current time of day isused. 
See the specification for thestrf time 0 function in C fortheformatconversionsthatare 
guaranteed to be available A public-domain version of strftime(3) and a man page for it are 
shipped with gawk; if that version wasusedto build gawk, then all of the conversions 
described in that man page are avail able to gawk. 


STRING CONSTANTS 

String constants in awk are sequences of characters enclosed between double quotes (■). Within strings, certai n escape 
sequences are recognized, asin C.These are 

\\ A literal backslash. 

\a The "alert" character; usually the ASCI I BEL character. 

\b Backspace. 

\f Formfeed. 

\n Newline. 
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\r 

\t 

\v 

\xhex digits 


\ ddd 


\ c 


Carriage return. 

Horizontal tab. 

Vertical tab. 

Thecharacter represented by the string of hexadecimal digits following the\x. As in C, all following 
hexadecimal digits are considered part of the escape sequence. (Thisfeature should tell us something about 
language design by committee.) For example, "\xib" is the ASC1 1 ESC (escape) character. 

Thecharacter represented by the 1-, 2-, or 3-digit sequence of octal digits For example, "\033" isthe 
ASCII ESC (escape) character. 

The literal character c. 


The escape sequences may also be used inside constant regular expressions (for example, /[\\t\f\n\r\v] / matches whitespace 
characters). 


FUNCTIONS 

Functions in awk are defined as follows: 

function n a me (p a r a me t e r list) { s t a t e me n t s } 

Functions are executed when called from within the action parts of regular pattern-action statements Actual parameters 
supplied in the function call are used to instantiate the formal parameters declared in the function. Arrays are passed by 
reference, other variables are passed by value. 

Functions were not originally part of the awk language, so the provision for local variables is rather clumsy: They are declared 
as extra parameters in the parameter list. The convention is to separate local variables from real parameters by extra spaces in 
the parameter list. For example 

function f(p, q, a, b) { # a & b are local 
. } 

/abc/ { ... ; f(1, 2) ; } 

The left parenthesis in a function call is required to immediately follow the function name, without any intervening 
whitespace. This is to avoid a syntactic ambiguity with the concatenation operator. This restriction does not apply to the 
built-in functions listed earlier. 

Functions may call each other and may be recursive. Function parameters used as local variables are initialized to the null 
string and the number zero upon function invocation. 

The word tunc may be used in place of function. 

EXAMPLES 

Print and sort the login names of all users: 

BEGIN { FS = } 

{ print $1 j “sort 11 } 

Count lines in afile 

{ nlines++ } 

END { print nlines } 

Precede each line by its number in thefile: 

{ print FNR, $0 } 

Concatenate and line number (a variation on atheme): 

{ print NR, $0 } 
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SEE ALSO 

egrep(l), getpid(2), getppid(2), getpgrp(2), getuid(2), geteuid(2), getgid(2), getegid(2), get-groups(2) 

TheAWK Programming Language, Alfred V. A ho, Brian W. Kernighan, Peter J. Weinberger, Addison-W esley, 1988. ISBN 
0-201-07981-X. 

TheGAWK Manual, Edition 0.15, published by theFreeSoftwareFoundation, 1993. 

P0SIX COMPATIBILITY 

A primary goal for gawk is compatibility with the standard, as well as with the latest version of awk. T o this end, gawk 
incorporates the following user-visible features that are not described in the awk book, but are part of awk in System V 
Released and arein thestandard. 

The-v option for assigning variables before program execution startsisnew. The book indicates that command-linevari able 
assignment happens when awk would otherwise open the argument as a file which is after the begin block is executed. 

H owever, in earlier implementations, when such an assignment appeared before any filenames, the assignment would happen 
beforetheBEGiN block was run. Applications came to depend on this "feature." When awk was changed to match its 
documentation, this option was added to accommodate applications that depended upon the old behavior. (This feature was 
agreed on by both the AT & T and G N U developers.) 

T he -w option for implementation-specific features isfrom the standard. 

When processing arguments, gawk uses the special option — to signal theend of arguments. In compatibility mode, it will 
warn about, but otherwise ignore undefined options. In normal operation, such arguments are passed on to the awk program 
for it to process. 

The awk book does not define the return value of srando. The System V Release 4 version of awk (and thestandard) has it 
return the seed it was using, to allow keeping track of random number sequences. Therefore srando in gawk also returns its 
current seed. 

Other new features are: the use of multiple-f options (from M KS awk); the environ array; the\a, and \v escape sequences 
(done originally in gawk and fed back into AT&T's version); thetoiowero and touppero built-in functions (from AT&T); 
and theC conversion specifications in printf (done first in AT&T's version). 

GNU EXTENSIONS 

gawk has some extensions to awk. They are described in this section. All the extensions described here can be disabled by 
invoking gawk with the-wcompat option. 

The following features of gawk are not available in awk: 

The \x escape sequence. 

The systimef ) and strftime( ) functions. 

The special filenames available for I/O redirection are not recognized. 

TheARGiND and errno variables are not special. 

T he ignorecase variable and its side effects. 

TheFiELDwiDTHs variable and fixed width field splitting. 

N o path search is performed for files named via the -f option. Therefore, theAWKPATH environment variable is not special. 
The use of next file to abandon processing of the current input file. 

The use of delete array to delete the entire contents of an array. 

Theawk book does not define the return value of the closed function, gawk’scioseo returns the valuefrom fciose(3), or 
pciose(3), when closing a file or pipe, respectively. 

When gawk is invoked with the-w compat option, if the fs argument to the-F option ist, then fs will beset to the tab 
character. Si nee this is a rather ugly special case, it is not the default behavior. T his behavior also does not occur if -wposix 
has been specified. 
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HISTORICAL FEATURES 

There are two features of historical awk implementations that gawk supports First, it is possible to call the length o built-in 
function not only with no argument, but even without parentheses! T hus, this: 
a = length 

is the same as either of these: 

a = length)) 
a = length($0) 

This feature is marked as "deprecated" in the standard, and gawk will issue a warning about its use if -w lint isspecified on 
thecommand line 

The other feature istheuseof either the continue or the break statements outside the body of awhile, for, or do loop. 

T raditional awk implementations have treated such usage as equivalent to the next statement, gawk will support this usage 
if -w compat has been specified. 

EN VIRO N M EN T VARIABLES 

If posixlycorrect exists in the environment, then gawk behaves exactly as if - -posix had been specified on thecommand 
line. If --lint has been specified, gawk will issueawarning message to this effect. 

BUGS 

The-F option is not necessary given the command-line variable assignment feature; it remains only for backwards compat¬ 
ibility. 

If your system actually has support for /dev/f d and the associated /dev/stdin, /dev/stdout, and /dev/stderr files, you may get 
different output from gawk than you would get on a system without those files. When gawk interprets these files internally, it 
synchronizes output to the standard output with output to /dev/stdout, while on a system with those files, the output is 
actually to different open files. C aveat emptor. 

VERSION INFORMATION 

T his man page documents gawk, version 2.15. 

Starting with the 2.15 version of gawk, the-c, -v, -c, -d, -a, and -e options of the 2.11 version are no longer recognized. This 
fact will not even be documented in the manual page for the next major version. 

AUTHORS 

Theoriginal version of awk was designed and implemented by Alfred Aho, Peter Weinberger, and Brian Kernighan of AT&T 
Bell Labs. Brian Kernighan continues to maintain and enhance it. 

Paul Rubin and Jay Fenlason, of the Free Software Foundation, wrote gawk, to be compatible with theoriginal version of awk 
distributed in thesa/enth edition. John W oods contributed a number of bugfixes. DavidT rueman, with contributions from 
Arnold Robbins, made gawk compatible with thenew version of awk. Arnold Robbinsisthe current maintainer. 

The initial DOS port was done by Conrad Kwok and Scott G arfinkle. Scott Deifik is the current DOS maintainer. Pat 
Rankin did theportto VM S, and M ichal Jaegermann did theportto the Atari ST. The port to OS/2 wasdoneby Kai Uwe 
Rommel, with contributions and help from Darrel Hankerson. 

BUG REPORTS 

If you find a bug in gawk, please send electronic mail to 
bug-gnu-utils@prep.ai.mit. edu, 

with a copy to arnoid@gnu. ai. mit. edu. Please include your operating system and its revision, the version of gawk, whatC 
compiler you used to compile it, and a test program and data that are as small as possiblefor reproducing the problem. 
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Before sending a bug report, please do two things. First, verify that you have the latest version of gawk. M any bugs (usually 
subtle ones) are fixed at each release, and if yours is out of date, the problem may already have been solved. Second, please 
read this man page and the reference manual carefully to be sure that what you think is a bug really is, instead of just a quirk 
in the language. 

ACKNOWLEDGMENTS 

Brian Kernighan of Bell Labs provided valuable assistance during testing and debugging. 

Wethankhim. 

Free Software Foundation, 24 N ovember!994 
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gcai— D isplays month/year calendar sheets, eternal holiday lists for Julian and Gregorian years, and fixed date warning 
I i sts— al I i n a vari ety of ways. 

SYNOPSIS 

gcal [[ Option... ] [ %D a t e ][@File... ]] [ Command ] 

DESCRIPTION 

gcai isaprogram similar the standard calendar programs BSD-car and calendar, 
gcai d isplays Gregorian calendars, Julian calendars (before September 1752). 

If gcai is started without any options or commands a calendar of the current month is displayed. 

If the calendar of a definite year is wanted, the year must be fully specified. For example, gcai 94 displays a year calendar of 
the year 94, not of the year 1994. 

If two arguments are given in the command part, the first argument denotes the month and the second argument denotes the 
year. In case any illegal commands are given running gcai, the program will use internal defaults 

TheGregorian Reformation isassumed to have occurred in 1752 on the 3rd of September. T en days following that date 
were eliminated by the reformation, so the calendar for that month is a bit unusual. 

MORE PROGRAM INFORMATION 

You get more program information if you start gcai as follows: 

gcal -h gcal -? gcal -help 
resp., 

gcal -hh gcal ■?? gcal -long - help [=ARG] j[=?] gcal -usage[ =ARG] j [=? ] 

A hypertext file gcai.info containing detailed online information should be available, which you can inspect using your 
GNU Infobrowser. 

COPYRIGHT 

gcai copyright© 1994,1995,1996 by ThomasEsken. This software doesn't claim completeness, correctness, or usability. 
On principle, I will not be liable for any damages or losses (implicit or explicit), which result from using or handling my 
software. If you use this software, you agree without anyexception to this agreement, which binds you legally. 

gcai is free software and distributed under thetermsof theGN U General Public License; published by the Free Software 
Foundation; version 2 or (at your option) any later version. 

Any suggestions, improvements, extensions, bug reports, donations, proposals for contract work, and so forth are welcome! 
If you like this tool, I'd appreciate a postcard from you! 

Enjoy it = 8 ") 
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AUTHOR 

T homas Esken (esken@uni-muenster.de) 
lm H agenfeld 84 
D -48147 M uenster; G ermany 
Phone: +49 251 232585 

SEE ALSO 

cal(l), calendar(l) 

16 July 1996 
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gcc, g++ — GNU project C and C++ Compiler (v2.7) 

SYNOPSIS 

gcc [ option j f i I ename ]. . . 
g++ [ option j f i I ename ]... 

WARNING 

The information in this man page is an extract from the full documentation of theGN U C compiler and is limited to the 
meaning of the options. 

This man page is not kept up-to-date except when volunteers want to maintain it. If you find a discrepancy between the man 
page and the software, please check the into file, which istheauthoritativedocumentation. 

If we find that the things in this man page that are out of date cause significant confusion or complaints, we will stop 
distributing the man page. The alternative, updating the man page when we update the into file, is impossible because the 
restoftheworkofmaintainingGNU CC leaves us no timefor that. TheGN U project regards man pages as obsolete and 
should notletthem take ti me away from other things. 

For complete and current documentation, refer to the info file gcc or the manual Using and Porting GNU CC (for version 
2.0). Both are made from theT exinfo source file gcc. texinto. 

DESCRIPTION 

TheC and C++compilers are integrated. Both process input files through one or more of four stages: preprocessing, 
compilation, assembly, and linking. Source filename suffixes identify the source language, but which name you use for the 
compiler governs default assumptions 

gcc Assumes preprocessed (.i) files are C and assumes C-style linking. 

g++ Assumes preprocessed (. i) files are C++and assumes C-H-style linking. 

Suffixes of source filenames indicate the language and kind of processing to be done: 

.c C source; preprocess, compile, assemble 

.c C ++source; preprocess, compile, assemble 

.cc C ++source; preprocess, compile, assemble 

.cxx C ++source; preprocess, compile, assemble 

.m Objective-C source; preprocess, compile assemble 

.i Preprocessed C; compile, assemble 

.ii Preprocessed C++; compile, assemble 

.s Assembler source; assemble 
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.s Assembler source; preprocess, assemble 

.h Preprocessor file; not usually named on command line 

Files with other suffixes are passed to the linker. Common cases include 

.0 Object file 
.a Archive file 

Linking is always the last stage unless you use one of the -c, -s, or -e options to avoid it (or unless compilation errors stop 
the whole process). For the link stage, all .0 files corresponding to sourcefiles, -1 libraries, unrecognized filenames (including 
named .0 object files, and .a archives) are passed to the linker in command-line order. 


OPTIONS 

Options must be separate -dr is quite different from -d -r. 

M ost-f and -w options have two contrary forms: -fname and -fno-name (or-wname and -wno-name). Only the nondefault forms 
are shown here. 

H ere isa summary of all theoptions, grouped by type. Explanationsarein thefollowing sections. 

Overall Options 

-c -S -E -0 file -pipe -v -x language 


Language Options 


-ansi 

-fall-virtual 

-fcond-mismatch 

-fdollars-in-identifiers 

-fenum-int-equiv 

-fexternal-templates 

-fno-asm 

-fno-builtin 

-fno-strict-prototype 

-fsigned-bitfields 

-fsigned-char 

-fthis-is-variable 

-funsigned-bitfields 

-funsigned-char 

-fwritable-strings 

-traditional 

-traditional-cpp 

-trigraphs 

Warning Options 



-fsyntax-only 

-pedantic 

-pedantic-errors 

-w -W -Wall 

-Waggregate-return 

-Wcast-align 

-Wcast-qual 

-Wchar-subscript 

-Wcomment 

-Wconversion 

-Wenum-clash 

-Werror 

-Wformat 

-Wid-clash-len 

-Wimplicit 

-Winline 

-Wmissing-prototypes 

-Wmissing-declarations 

-Wnested-externs 

-Wno-import 

-Wparentheses 

-Wpointer-arith 

-Wredundant-decls 

-Wreturn-type 

-Wshadow 

-Wstrict-prototypes 

-Wswitch 

-Wtemplate-debugging 

-Wtraditional 

-Wtrigraphs 

-Wuninitialized 

-Wunused 

-Wwrite-strings 


Debugging Options 

-a -dletters -fpretend-float -g -gl evel -gcoff -gxcoff -gxcoff+ -gdwarf -gdwarf+ -gstabs -gstabs+ -ggdb -p -pg - 
save- temps -print-file-name=l i brary -print-libgcc-file-name - print-prog-name=program 


Optimization Options 

-fcaller-saves 
-fdelayed-branch 
-ffast-math 
-fforce-mem 


-fcse-follow-j umps 
-felide-constructors 
-ffloat-store 
-finline-functions 


-fcse-skip-blocks 
-fexpensive-optimizations 
-fforce-addr 
-fkeep-inline-functions 
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-fmemorize-lookups -fno-default-inline -fno-defer-pop 

-fno-function-cse -fno-inline -fno-peephole 

-fomit-frame-pointer -frerun-cse-after-loop -fschedule-insns 

-fschedule-insns2 -fstrength-reduce -fthread-jumps 

-funroll-all-loops -funroll-loops -0 -02 

Preprocessor Options 

-Aassertion -C -dD -dM -dN -Dma cro[=defn ] -E -H- idirafter d i r -include file -imacros file -iprefix f i I e — 
iwithprefix dir -M -MD -MM -MMD -nostdinc -P -Umacro -undef 

Assembler 0 ption 

-Wa,opt i on 

Linker Options 

-llibrary -nostartfiles -nostdlib -static -shared -symbolic -Xlinkerno pt i o n-Wl,o pti o n -u symbol 

Directory Options 

-Bpr efi x -Idi r -I- -Ldi r 

Target Options 

-b machine -V version 

Configuration-Dependent Options 

M 680x0 Options 

-m68000-m68020 -m68020-40-m68030-m68040-m68881 -mbitfield -mc68000 -mc68020 -mfpa -mnobitfield -mrtd -nshort -msoft- 
float 

1 /AX Options 
-mg -mgnu -munix 
SPARC Options 

-mepilogue -mfpu -mhard-float -mno-fpu -mno-epilogue -msoft-float -msparclite -mv8 -msupersparc -mcypress 

Convex Options 

-margcount -mcl -mc2 -mnoargcount 

AM D29K Options 

-m29000-m29050 -mbw -mdw -mkernel-registers -mlarge -mnbw -mnodw -msmall -mstack-check -muser-registers 

M 88K Options 

-m88000 -m88100 -m88110 -mbig-pic 

-mcheck-zero-division -mhandle-large-shift 

-midentify-revision -mno-check-zero-division 

-mno-ocs-debug-info -mno-ocs-frame-position 

-mno-optimize-arg-area -mno-serialize-volatile 

-mno-underscores -mocs-debug-info 

-mocs-frame-position -moptimize-arg-area 

-mserialize-volatile -mshort-data-num 

-msvr3 -msvr4 -mtrap-large-shift 

-muse-div-instruction -mversion-03.00 

-mwarn-passed-structs 
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RS6000 Options 
-mfp-in-toc -mno-fop-in-toc 
RT Options 

-mcall-lib-mul -mfp-arg-in-fpregs -mfp-arg-in-gregs 

-mfull-fp-blocks -mhc-struct-return -min-line-mul 

-mminimum-fp-blocks -mnohc-struct-return 


M IPS Options 


-mcpu=cpu type -mips2 -mips3 


-mint64 -mlong64 


-mlonglong128 

-mmips-as 

-mgas 

-mrnames 

-mno-rnames 

-mgpopt 

-mno-gpopt 

-mstats 

-mno-stats -mmemepy -mno-memepy -mno-mips-tfile 




-mmips-tfile 

-msoft-float 

-mhard-float 

-mabicalls 


-mno-abicalls -mhalf-pic -mno-half-pic -G num -nocpp 

(386 Options 

-m486 -mno-486 -msoft-float-mno-fp-ret-in-387 
HPPA Options 

-mpa-rise-1-0 -mpa-rise-1-1 -mkernel -mshared-libs- mno-shared-libs-mlong-calls-mdisable-fpregs-mdisable- 


indexing-mtrailing- colon 

i960 Options 

-mepu-type 

-mnumerics 

-msoft-float 

-mleaf-procedures 

-mno-leaf-procedures 

-mtail-call 

-mno-tail-call 

-mcomplex-addr 

-mno-complex-addr 

-mcode-align 

-mno-code-align 

-mic-compat 

-mic2.0-compat 

-mic3.0-compat 

-masm-compat 

-mintel-asm 

-mstrict-align 

-mno-strict-align 

-mold-align 

-mno-old-align 

DEC Alpha Options 

-mfp-regs -mno-fp-regs -mno- 

-soft-float -msoft-float 



System V Options 

-G -Qy -Qn -YP,paths -Ym,dir 

Code-Generation Options 
-fcall-saved-r eg -fcall-used- 
reg -ffixed-reg -finhibit- 
size-directive -fnonnull- 
objects -fno-common -fno-ident 
-fno-gnu-linker -fpcc-struct- 
return -fpic -fPIC -freg- 
struct- return -fshared-data - 
fshort-enums -fshort-double - 
fvolatile -fvolatile-global - 
fverbose-asm 
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OVERALL OPTIONS 

-x i anguage Specify explicitly the i anguage for the following input files (rather than choosing a default based on the 
filename suffix). This option applies to all following input files until the next -x option. Possible values of 
anguage arec, objective-c, c-header, C++,cpp-output, assembler, and assembler-with-cpp. 

-x none Turn off any specification of a language, so that subsequent files are handled according to their filename 

suffixes (as they are if-x has not been used at ail). 

If you want only some of the four stages (preprocess, compile, assemble, link), you can use-x (or filename suffixes) to tell gcc 
whereto start, and one of the options -c, -s, or -e to say where gcc is to stop. Note that some combinations (for example, -x 
cpp-output -e) instruct gcc to do nothing at all. 

-c Compile or assemble the source files, but do not link. The compiler output is an object file corresponding 

to each source file. 

By default, gcc makes the object filename for a source file by replacing the suffix .c, .i, .s, and so on, with 
. 0 . Use -o to select another name 

gcc ignores any unrecognized input files (those that do not require compilation or assembly) with the-c 
option. 

-s Stop after the stage of compilation proper; do not assemble. The output is an assembler code file for each 

nonassembler input file specified. 

By default, gcc makes the assembler filename for a source file by replacing the suffix .c, .i, and so on, with 

.s. U se -o to select another name 

gcc ignores any input files that don't require compilation. 

-e Stop after the preprocessing stage; do not run the compiler proper. The output is preprocessed source 

code, which is sent to the standard output, 
gcc ignores input files that don't require preprocessi ng. 

-o f i i e Place output in file f i i e. This applies regardless to whatever sort of output gcc is producing, whether it be 

an executable file, an object file, an assembler file, or preprocessed C code. 

Sinceonly one output file can be specified, it does not make sense to use-owhen compiling more than 
oneinput file, unless you are producing an executable file as output. 

If you do not specify -o, the default is to put an executable file in a. out, the object filefor source .suffi x in 
source .o, its assembler file in sour ce .s, and all preprocessed C source on standard output. 

-v Print (on standard error output) the commands executed to run thestagesof compilation. Also print the 

version number of the compiler driver program and of the preprocessor and the compiler proper. 

-pipe Use pipes rather than temporary files for communication between the various stages of compilation. This 

fails to work on some systems where the assembler cannot read from a pipe; but theGN U assembler has 
no trouble. 

LANGUAGE OPTIONS 

T he following options control the dialect of C that the compiler accepts: 

-ansi Support all AN SI standard C programs. 

Thisturnsoff certain features of GN U C that are incompatiblewith ANSI C, such as the asm, 
inline, and typeof keywords, and predefined macros such asunix and vax that identify the type 
of system you are using. It also enables the undesirable and rarely used AN SI trigraph feature, 
and disallows* as part of identifiers. The alternate keywords __asm_, __extension_, 

_inline _, and __typeof_ continue to work despite -ansi. You would not want to use them 

in an ANSI C program, of course, but it is useful to put them in header files that might be 
included in compilations done with -ansi. Alternate predefined macros such as__unix_ and 
__vax_ are also available, with or without -ansi. 

The -ansi option does not cause non-ANSI programs to berqected gratuitously. For that, - 
pedantic is required in addition to -ansi. 
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-fno-asm 

-fno-builtin 

-fno-strict-prototype 

-trigraphs 

-traditional 


-traditional-cpp 

-fdollars-in-identifiers 

-fenum-int-equiv 
-fexternal-templates 


-fall-virtual 


-fcond-mismatch 

-fthis-is-variable 

-funsigned-char 


The preprocessor predefines a macro __strict_ansi_ when you use the -ansi option. Some 
header files may notice this macro and refrain from declaring certain functionsor defining 
certain macros that the AN SI standard doesn't call for; this is to avoid interfering with any 
programs that might use these names for other things. 

Do not recognize asm, inline, or typeof as a keyword. These words may then be used as 

identifiers. Y OU can use_ asm_,_inline_ , and_ typeof _instead, -ansi implies -fno-asm. 

Don't recognize built-in functionsthat do not begin with two leading underscores. Currently, 
the functions affected include_exit, abort, abs, alloca, cos, exit, tabs, labs, memcmp, memcpy, 
sin, sqrt, strcmp, strcpy,and strlen. 

The -ansi option prevents aiioca and_exit from being built-in functions. 

T reat a function declaration with no arguments, such asint too();, as C would treat it— as 
saying nothing about the number of arguments or their types (C++only). N ormally, such a 
declaration in C++means that the function too takes no arguments. 

Support AN SI C trigraphs. The -ansi option implies -trigraphs. 

Attempt to support some aspects of traditional C compilers. For details, seetheGNL/ C 
M anua/; the duplicate list here has been deleted so that we won't get complaints when it is out 
of date. 

But one note about C ++ programs only (not C). -traditional has one additional effect for 
C ++: assignment to this is permitted. This is the same as the effect of -fthis-is-variabie. 
Attempt to support some aspects of traditional C preprocessors. This includes the items that 
specifically mention the preprocessor previously, but none of the other effects of -traditional. 
Permit the use of $ in identifiers (C ++only). You can also use -fno-doiiars-in-identifiersto 
explicitly prohibit use of $. (GNU C++allows $ by default on some target systems but not 
others.) 

Permit implicit conversion of int to enumeration types (C ++ only). N ormally GN U C++ 
allows conversion of enum to int, but not the other way around. 

Produce smaller code for template declarations, by generating only a single copy of each 
template function where it is defined (C++only). T o use this option successfully, you must also 
mark all files that use templates with either #pragma implementation (the definition) or#pragma 
interface (declarations). 

When your code is compiled with -f external-templates, all template instantiations are external. 
You must arrange for all necessary instantiations to appear in the implementation file; you can 
do this with a typedet that references each instantiation needed. Conversely, when you compile 
using the default option -fno-externai-tempiates, all template instantiations are explicitly 
internal. 

Treat all possible member functionsasvirtual, implicitly. All member functions (except for 
constructor functions and new or delete member operators) are treated as virtual functions of 
the class where they appear. This does not mean that all calls to these member functionswi II be 
made through theinternal table of virtual functions. U nder some circumstances, the compiler 
can determine that a call to agiven virtual function can be made directly; in these cases, the 
calls are direct in any case. 

Allow conditional expressions with mismatched types in the second and third arguments. The 
valueof such an expression isvoid. 

Permit assignment to this (C ++ only). The incorporation of user-defined free store manage¬ 
ment into C++ has made assignment to this an anachronism. Therefore, by default it is invalid 
to assign to thiswithin a class member function. H owever, for backwards compatibility, you 
Can make it valid with -fthis-is-variable. 

Let the type char beunsigned, like unsigned char. 

Each kind of machine has a default for what char should be. It is either like unsigned char by 
default or like signed char by default. 
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-fsigned-char 


-fsigned-bitfields 
-funsigned-bitfields 
-fno-signed-bitfields 

-fno-unsigned-bitfields 
-fwritable-strings 


Ideally, a portable program should always use signed char or unsigned char when it depends on 
the signedness of an object. But many programs have been written to use plain char and expect 
itto be signed, or expect itto beunsigned, depending on the machines they were written for. 
This option, and its inverse, lets you make such a program work with the opposite default. 

The type char is always a distinct type from each of signed char and unsigned char, even though 
its behavior is always just like oneof those two. 

Let the type char be signed, like signed char. 

N ote that this is equivalent to -f no-unsigned-char, which is the negative form of -funsigned- 
char. Likewise, -fno-signed-char is equivalent to -f unsigned-char. 

These options control whether a bitfield is signed or unsigned, when declared with no explicit 
or unsigned qualifier. 

By default, such a bitfield is signed, because this is consistent: The basic integer types such as 
int 

signed are signed types. 

H owever, when you specify -traditional, bitfields are all unsigned no matter what. 

Store string constants in the writable data segment and don't uniquize them. This is for 
compatibility with old programswhich assume they can write into string constants, -tradi¬ 
tional also has this effect. 

Writing into string constants is a very bad idea; constants should be constant. 


PREPROCESSOR OPTIONS 


These options control theC preprocessor, which is run on each C source file before actual compilation. 


If you use the -e option, gcc does nothing except preprocessing. Some of these options make sense only together with -e 
because they cause the preprocessor output to be unsuitable for actual compilation. 


-include file 


-imacros file 


-idirafter di r 


-iprefix prefix 
-iwithprefix di r 

-nostdinc 


-nostdinc++ 

-undef 

-E 

-C 


Process f i i e as input before processing the regular input file. In effect, the contents of f i i e 
are compiled first. Any -d and -u options on the command line are always processed before 
-include f i i e, regardless of the order in which they are written. All the -include and -imacros 
options are processed i n the order in which they are written. 

Process f i i e as input, discarding the resulting output, before processing the regular input file 
B ecause the output generated from f ii e is discarded, the only effect of -imacros file is to make 
the macros defined in f i i e available for use in the main input. The preprocessor evaluates any 
-d and -u options on the command line before processing -imacros file, regardless of the order 
in which they are written. All the -include and -imacros options are processed in the order in 
which they are written. 

Add the di rectory di r to the second include path. The directories on the second include path 
are searched when a header fileisnot found in any of thedirectories in themain include path 
(the one that -i adds to). 

Specify pr ef i * as the prefix for subsequent -iwithprefix options. 

Add a directory to the second include path. The directory's name is made by concatenating 
p r ef i x and di r, where pr ef i * was specified previously with -iprefix. 

Do not search the standard system directories for header files. Only the directories you have 
specified with -i options (and the current directory, if appropriate) are searched. 

By using both -nostdinc and -i-, you can limit the include file search file to only those 
directories you specify explicitly. 

Do not search for header files in the C-H- specific standard directories, but do still search the 
other standard directories. (Thisoption isused when building iibg++.) 

Do not predefine any nonstandard macros (including architecture flags). 

Run onlytheC preprocessor. Preprocess all theC source files specified and output the results to 
standard output or to the specified output file 
T ell the preprocessor not to discard comments. U sed with the-E option. 
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-p 

-M [-MG] 


-MM [-MG] 


-MD 


-MMD 

-H 

-Aquest i on (answer ) 


-Aques t i on ( answer 


-Dma c r o 
-Dmac r o =def n 


-Uma c r o 


-dM 


-dD 


-dN 


T ell the preprocessor not to generate #iine commands. U sed with the -e option. 

T ell the preprocessor to output a rule suitable for make describing the dependencies of each 
object file. For each source file, the preprocessor outputs one make -rule whose target isthe 
obj ect fi lename for that source file and whose dependencies are all the files that have been 
included with #inciude. This rule may be a single line or may be continued with \-newlineif it 
is long. The list of rules is printed on standard output instead of the preprocessed C program. 

-m implies -e. 

-mg says to treat missing header files as generated files and assumethey livein the same directory 
as the source file. It must be specified in addition to -m. 

Like -m but the output mentionsonly the user header files included with #inciude "file ". 
System header files included with #mciude < file > are omitted. 

Like -m but the dependency information is written to files with names made by replacing .0 
with .d attheend of the output filenames. This is in addition to compiling thefile as specified; 
-md does not inhibit ordinary compilation the way -m does. 

TheM ach utility md can be used to merge the .d files into a single dependency file suitable for 
using with the make command. 

Like -md except mention only user header files, notsystem header files. 

Print the name of each header file used, in addition to other normal activities. 

Assert the answer answer forquesti on, in case it is tested with a preprocessor conditional such as 
#if #q u e s t i on (answer ). -A- disables the standard assertions that normally describe the target 
machine. 

Assert the answer answer f 0 r q u e s t i on, in case it is tested with a preprocessor conditional such as 
#if # question ( answer >. -A-disables the standard assertions that normally describe the target 
machine. 

Define macro macro with the string 1 as its definition. 

Define macro macro asdef n. All instances of -d on the command line are processed before any 
-u options. 

Undefine macro macro, -u options are evaluated after all -d options, but before any -include and 
-imacros options. 

T ell the preprocessor to output only a list of the macro definitions that are in effect at the end 
of preprocessing. Used with the -e option. 

Tell the preprocessor to pass all macro definitions into the output, in their proper sequence in 
the rest of the output. 

Like -dD except that the macro arguments and contents are omitted. Only#define name is 
included in theoutput. 


ASSEMBLER OPTION 

-Wa,0pt i on 


Passopti on as an option to the assembler. If opt i on contains com mas, it is split into multiple 
options at the commas. 


LINKER OPTIONS 

These options come into play when the compiler links object files into an executable output file. They are meaningless if the 
compiler is not doing a link step. 

obj ect - f i 1 e-name A filename that does not end in a special recognized suffix is considered to name an object file 

or library. (Object files are distinguished from libraries by the linker according to thefile 
contents.) If gcc does a link step, these object files are used as input to the linker. 

-l! i brary U se the library named library when linking. 

T he linker searches a standard list of directories for the library, which is actually a file named 
lib 1 i brary .a. The linker then uses thisfi leas if it had been specified precisely by name. 
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-lobjc 

-nostartfiles 

-nostdlib 

-static 

-shared 

-symbolic 

-Xlinker option 


-Wl,option 
-u symbol 


The directories searched include several standard system directories plus any that you specify 

with -L. 

N ormally, the files found this way are library files— archive files whose members are object files. 
The linker handles an archive file by scanning through it for members that define symbols that 
have so far been referenced but not defined. H owever, if the linker finds an ordinary object file 
rather than a library, the object file is linked in the usual fashion. The only difference between 
using an -1 option and specifying a filename is that-I surrounds i i br ary with lib and .a and 
searches several directories. 

You need this special case of the -1 option in order to link an Objective C program. 

Do not use the standard system startup files when linking. Thestandard libraries are used 
normally. 

Don't use the standard system libraries and startup files when linking. Only the files you specify 
will be passed to the linker. 

On systems that support dynamic linking, this prevents linking with the shared libraries. On 
other systems thisoption has no effect. 

Produce a shared object which can then be linked with other objects to form an executable 
Only a few systems support thisoption. 

Bind references to global symbols when building a shared object. W am about any unresolved 
references (unless overridden by the link editor option -xiinker -z -xiinker def s). Only a few 
systems support thisoption. 

Pass option as an option to the linker. You can use this to supply system-specific linker options 
which GNU CC does not know how to recognize. 

If you want to pass an option that takes an argument, you must use -xiinker twice once for the 
option and once for the argument. For example, to pass -assert definitions, you mustwrite- 
Xlinker -assert -Xiinker def initions. 11 does not work to write -Xiinker "-assert 
definitions", because this passes the entire string as a single argument, which is not what the 
linker expects. 

Pass option as an option to the linker. If option contains commas, it issplit into multiple 
options at the commas. 

Pretend thesymbol symbol is undefi ned, to force linking of library modules to define it. You 
can use-u multiple timeswith different symbols to force loading of additional library modules. 


DIRECTORY OPTIONS 

These options specify directories to search for header files, for libraries, and for parts of the compiler: 

-idi r Append directory di r to the list of directories searched for includefiles. 

-i- Any directories you specify with -i options before the-i- option are searched only for the case 

of #inciude "file"; they are not searched for #inciude <fiie>. 

If additional directories are specified with -i options after the-i-, these directories are searched 
for all #inciude directives. (Ordinarily all -i directories are used thisway.) 

In addition, the-i- option inhibits the use of the current directory (where the current input file 
came from) as the first search directory for #inciude ■ file ".Thereisnowaytooverridethis 
effect of -i-. W ith -i. you can specify searching the directory that was current when the 
compi ler was invoked. T hat is not exactly the same as what the preprocessor does by default, 
but it is often satisfactory. 

-i- does not inhibit the use of thestandard system directories for header files. Thus, -i- and 
-nostdinc are independent. 

-Ldi r Add directory di r to the list of directories to be searched for- 1 . 

-Bp refix Thisoption specifies where to find the executables, libraries, and data files of the compi ler itself. 

The compiler driver program runs one or more of the subprograms cpp, cci (or, for C++, 
cci plus), as, and id. It tries p ref i * as a prefix for each program it tries to run, both with and 
without mac hi ne / version /. 
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For each subprogram to be run, the compiler driver first tries the -b prefix, if any. If that name 
is not found, or if -b was not specified, the driver tries two standard prefixes, which are/usr/ 
iib/gcc/ and /usr/local/lib/gcc-lib/. If neither of those results in a filename that is found, the 
compiler driver searches for the unmodified program name, using the directories specified in 
your path environment variable 

T he runtime support fileiibgcc.a is also searched for using the -b prefix, if needed. If it is not 
found there the two standard prefixes (preceding paragraph) are tried, and that is all. The file is 
left out of the link if it is not found by those means. M ost ofthetime, on most machines, 
libgcc.a is not actually necessary. 

You can get a similar result from the environment variable gcc_exec prefix; if it is defined, its 
value is used as a prefix in the same way. If both the-B option and theGcc_EXEc_PREFix variable 
are present, the-B option is used first and the environment variable value second. 


WARNING OPTIONS 


Warnings are diagnostic messages that report constructions that are not inherently erroneous but are risky or suggest there 
may have been an error. 

These options control the amount and kinds of warnings produced by GN U CC: 


-fsyntax-only 

-w 

-Wno-import 

-pedantic 


-pedantic-errors 

-W 


C heck the code for syntax errors, but don't emit any output. 

Inhibit all warning messages. 

I nhibit warning messages about the use of //import. 

Issue all thewarnings demanded by strict AN SI standard C; reject all programsthatuse 
forbidden extensions. 

Valid ANSI standard C programs should compile properly with or without this option (though 
a rare few will require -ansi). H owever, without this option, certain GNU extensions and 
traditional C features are supported as well. W ith this option, they arerqected. There is no 
reason to usethisoption; it exists only to satisfy pedants. 

-pedantic does not cause warning messages for use of the alternate keywords whose names begi n 
and end with Pedantic warnings are also disabled in the expression that followsextension. 
However, only system header files should use these escape routes; application programs should 
avoid them. 

Like -pedantic, except that errors are produced rather than warnings. 

Print extra warning messages for these a/ents: 

A nonvolatile automatic variable might be changed byacall to longjmp. These warnings are 
possi ble only in optimizing compilation. The compiler sees only the cal Is to setjmp. It cannot 
know where longjmp will be called; in fact, asignal handler could call it at any point in thecode. 
Asa result, you may get a warning even when there is in fact no problem because longjmp 
cannot in fact be called at the place which would cause a problem. 

A function can return either with or without a value. (Falling off the end of the function body 
is considered returning without a value.) For example, this function would evoke such a 
warning: 
too (a) 

{ 

if (a > 0) 
return a; 

} 


Spurious warnings can occur because GN U CC does not realize that certain functions 
(including abort and longjmp) will never return. 

An expression-statement or the left side of a comma expression contains no side effects. T o 
suppress thewarning, cast the unused expression to void. For example, an expression such as 
x[i, j] will causeawarning, but x[(void)i,j ] will not. 

An unsigned value is compared against zero with > or <=. 
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-Wimplicit 

-Wreturn-type 

-Wunused 


-Wswitch 


-Wcomment 

-Wtrigraphs 

-Wformat 

-Wchar-subscripts 

-Wuninitialized 


W am whenever a function or parameter is implicitly declared. 

Warn whena/er afunction isdefined with a return-type that defaults to int. Also warn about 
any return Statement with no return-value in afunction whose return-type isnotvoid. 

Warn whena/er a local variable is unused aside from its declaration, whenever afunction is 
declared static but never defined, and whenever a statement computes a result that is explicitly 
not used. 

Warn whena/er a switch statement has an index of enumeral type and lacks a case for one or 
more of the named codes of that enumeration. (The presence of a default label prevents this 
warning.) case labels outside the enumeration range also provokewarningswhen thisoption is 
used. 

W am whena/er a comment-start sequence / appears in a comment. 

W arn if any trigraphs are encountered (assumi ng they are enabled). 

Check cal Is to printf and scant, and so on, to make sure that the arguments supplied have 
types appropriate to the format string specified. 

W arn if an array subscript has type char. T his is a common cause of error, as programmers 
often forget that thistype is signed on some machines. 

An automatic variable is used without first being initialized. 

These warnings are possible only in optimizing compilation, because they require data flow 
information that is computed only when optimizing. If you don't specify-o, you simply won’t 
get these warnings. 

T hese warnings occur only for variables that are candidates for register allocation. T herefore, 
they do not occur for a variablethat is declared volatile or whose address istaken, orwhosesize 
is other than 1, 2, 4, or 8 bytes. Also, they do not occur for structures, unions, or arrays, even 
when they are in registers. 

N ote that there may be no warning about a variable that is used only to compute a value that 
itself is never used, because such computations may be deleted by dataflow analysis before the 
warnings are printed. 

These warnings are made optional becauseGNU CC is not smart enough to see all the reasons 
why the code might be correct despite appearing to have an error. H ere is one example of how 
this can happen: 

{ 

int x; 
switch (y) 

{ 

case 1: x = 1; 
break; 

case 2: x = 4; 
break; 

case 3: x = 5; 

} 

too (x); 

} 

If the value of y is always i, 2 , or 3 , then x is always initialized, but GN U CC doesn't know this. 
H ere is another common case: 

{ 

int save_y; 

if (change_y) save_y =y,y =new_y; 

if (change_y)y =save_y; 

} 

This has no bug because save_y is used only if it is set. 

Somespuriouswarningscan be avoided if you declare as volatile all thefunctionsyou use that 
never return. 



gcc, g++ 


185 


-wparentheses W arn if parentheses are omitted i n certai n contexts. 

-wtempiat e-debugging When using templates in a C++ program, warn if debugging is not yet fully available (C++ 

only). 

-wail All of the preceding -w options combined. These are all the options that pertain to usage that 

we recommend avoiding and that we believe is easy to avoid, even in conjunction with macros. 


The remaining-w... options are not implied by-waii because the/warn about constructions that we consider reasonableto 

use, on occasion, in clean programs. 

-wtraditionai Warn about certain constructs that behave differently in traditional andANSI C: 

M aero arguments occurring within string constants in the macro body. These would substitute 
the argument in traditional C, but are part of the constant in AN SI C. 

A function declared external in oneblock and then used after theend of theblock. 

A switch statement has an operand of type long. 

-Wshadow W am whena/er a local variable shadows another local variable. 

-wid-ciash-i en Warn whenever two distinct identifiers match in the first i en characters. This may help you 

prepare a program that will compilewith certain obsolete, brain-damaged compilers. 

-wpointer-arith W am about anything that depends on the size of a function type or of void. G N U C assigns 

these types a size of i, for convenience in calculations with void pointers and pointers to 
functions 

-wcast-quai Warn whenever a pointer is cast so as to remove a type qualifier from the target type. For 

example, warn if a const char is cast to an ordinary char. 

-wcast-aiign Warn whenever a pointer is cast such that the required alignment of the target is increased. For 

example, warn if a char iscast to an int on machines where integers can only be accessed at 
two- or four-byte boundaries. 

-Wwrite-strings G ive string constantsthetype const char[ length ] so that copying the address of one into a 

non-const char pointer will get a warning. These warnings will help you find at compile time 
code that can try to write into a string constant, but only if you have been very careful about 
using const in declarations and prototypes. Otherwise, it will just be a nuisance; this is why we 
did notmake-waii request these warnings. 

-wconversion W am if a prototype causes a type conversion that is different from what would happen to the 

same argument in the absence of a prototype. This includes conversions of fixed point to 
floating and vice versa, and conversions changing thewidth or signedness of a fixed point 
argument except when the same as the default promotion. 

-waggregate-return Warn if any functions that return structures or unions are defined or called. (In languages 

where you can return an array, this also elicits a warning.) 

-wstrict-prototypes Warn if a function is declared or defi ned without specifying the argument types. (An old-style 
function definition is permitted without a warning if preceded by a declaration which specifies 
the argument types.) 

-wmissing-prototypes Warn if a global function is defi ned without a previous prototype declaration. This warning is 
issued a/en if the definition itself provides a prototype. The aim is to detect global functions 
that fail to be declared in header files. 

-wmissing-deciarations Warn if a global function is defi ned without a previous declaration. Dosoeven if the definition 
itself provides a prototype. Usethisoption to detect global functionsthat are not declared in 
header files. 

-wredundant -decis Warn if anything is declared more than once in the same scope, even in cases where multiple 

declaration isvalid and changes nothing. 

-wnested-externs Warn if an extern declaration is encountered within an function. 

-wenum-ciash Warn about conversion between different enumeration types (C ++ only). 

-woverioaded-virtual (C ++ only.) In a derived class, the definitions of virtual functions must match the type signature 

of a virtual function declared in the base class. Usethisoption to request warnings when a 
derived class declares a function that may bean erroneous attempt to define a virtual function; 
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that is, warn when there is a function with the same name as a virtual function in the base class, 
but with a type signature that doesn't match any virtual functions from the base class. 

-winiine Warn if a function cannot beinlined, and either it was declared as inline or else the-f inline- 

functions option was given. 

-werror T reat warnings as errors abort compilation after any warning. 


DEBUGGING OPTIONS 

GN U CC has various special options that are used for debugging either your program or gcc: 

-g Produce debugging information in the operating system's native format (stabs, COFF.XCOFF, 

or DWARF). GD B (theGNU debugger) can work with thisdebugging information. 

0 n most systems that U9e stabs format, -g enables U9e of extra debugging information that only G D B 
can use; thisextra information makes debugging work better in G D B but will probably make 
other debuggers crash or refuse to read the program. If you want to control for certain whether 
to generate the extra information, use-gstabs, -gstabs, -gxcoff+, -gxcoff, -gdwarf+, or -gdwarf. 
U nlike most other C compilers, GN U CC allows you to use -g with -o. The shortcuts taken by 
optimized code may occasionally produce surprising results: Some variables you declared may 
not exist at all; flow of control may briefly movewhere you did notexpectit; some statements 
may not be executed because the/ compute constant results or their values were already at hand; 
some statements may execute in different places becausethe/ were moved out of loops. 

N evertheless, it proves possible to debug optimized output. This makes it reasonable to use the 
optimizer for programs that might have bugs. 


The following options are useful when GNU C C is generated with the capability for more than one debugging format. 


-ggdb 

-gstabs 

-gstabs+ 

-gcoff 

-gxcoff 

-gxcoff+ 

-gdwarf 

-gdwarf+ 


Produce debugging information in the native format (if that is supported), including GD B 
extensions if at all possible. 

Produce debugging information in stabs format (if that is supported), without GD B exten¬ 
sions. This is the format used by D BX on most BSD systems. 

Produce debugging information in stabs format (if that is supported), using GNU extensions 
understood only by theGN U debugger (GD B). The use of these extensions is likely to make 
other debuggers crash or refuse to read the program. 

Produce debugging information in C OFF format (if that is supported). This is the format used 
by SD B on most System V systems prior to System V Released 
Produce debugging information in XCOFF format (ifthat is supported). This is the format 
used bytheDBX debugger on IBM RS/6000 systems. 

Producedebugging information inXCOFF format (if that is supported), usingGNU 
extensions understood only by theGN U debugger (GD B). The use of these extensions is likely 
to make other debuggers crash or refuse to read the program. 

Produce debugging information in DWARF format (if that is supported). This is the format 
used by SD B on most System V Release 4 systems. 

Producedebugging information in DWARF format (if that is supported), usingGNU 
extensions understood only by theGN U debugger (GD B). The use of these extensions is likely 
to make other debuggers crash or refuse to read the program. 

-glevel 
-ggdbl e v e I 
-gstabsl eveI 

-gcoff I ev e I -gxcoff I e v eI 


-gdwarf i evei Request debugging information and also usei evei to specify how much information. The 

default level is 2. 

Level 1 produces minimal information, enough for making backtraces in parts of the program 
that you don't plan to debug. This includes descriptions of functions and external variables, but 
no information about local variables and no line numbers. 
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-p 

-pg 


-a 


—dl e 11 e r s 


-dM 

-dN 

-dD 

-dy 

-dr 

-dx 

-dj 

-ds 

-dL 

-dt 

-df 

-dc 

-dS 

-dl 

-dg 

-dR 

-dJ 

-dd 

-dk 

-da 

-dm 

-dp 

-fpretend-float 


-save-temps 


-print-file-name=li br a ry 


-print-libgcc-file-name 
-print-prog-name=pr o g r am 


Level 3 includes extra information, such as all themacro definitions presentin theprogram. 
Some debuggers support macro expansion when you use-g3. 

G enerate extra code to write profile information suitable for the analysis program prof. 

G enerate extra code to write profile information suitable for the analysis program gprof. 
Generate extra code to write profile information for basic blocks, which will record the number 
oftimeseach basic block isexecuted. Thisdata could be analyzed by aprogram like tcov. Note, 
however, that the format of the data is not what tcov expects. Eventually, GNU gprof should 
be extended to process this data. 

Says to makedebugging dumps during compilation at times specified bytetters. Thisisused 
for debugging the compiler. The filenames for most of the dumps are made by appending a 
word to the source filename (for example, foo.c.rti orfoo.c.jump). 

Dump all macro definitions at the end of preprocessing, and write no output. 

Dump all macro names, at the end of preprocessing. 

Dump all macro definitions at the end of preprocessing, in addition to normal output. 

Dump debugging information during parsing, to standard error. 

Dump after RTL generation, tof i i e. rti. 

J ust generate RT L forafunction instead of compiling it. Usually used with r. 

Dump after first jump optimization, to f i i e . jump. 

Dump after CSE (including the jump optimization that sometimes follows CSE), to f i i e . cse. 
D ump after loop optimization, to f i i e . loop. 

Dump after the second CSE pass (including the jump optimization that sometimes follows 
C SE), to f i I e . cse2. 

D ump after flow analysis, to f i i e . flow. 

D ump after instruction combination, tof i i e . combine. 

Dump after the first instruction scheduling pass, to f i i e . sched. 

D ump after local register allocation, to f i i e . ireg. 

D ump after global register allocation, to f i i e . greg. 

Dump after the second instruction scheduling pass, to f i i e ,sched 2 . 

Dump after last jump optimization, to f i i e .jump 2 . 

D ump after delayed branch scheduling, to f i i e .dbr. 

D ump after conversion from registers to stack, to f i i e .stack. 

Produce all the dumps listed previously. 

Print statistics on memory usage, attheend of the run, to standard error. 

Annotate the assembler output with a comment indicating which pattern and alternative was 
used. 

When running a cross-compiler, pretend that the target machine uses the same floating-point 
format as the host machine This causes incorrect output of the actual floating constants, but 
the actual instruction sequence will probably be the same as GN U CC would make when 
running on the target machine. 

Store theusual temporary intermediate files permanently; place them in thecurrent directory 
and namethem based on the source file. Thus, compilingfoo.c with -c -save-temps would 
produce filesfoo. cpp and foo.s, as well asfoo.o. 

Print the full absolute name of the library file i i brary would beused when linking, and do not 
do anything else. With this option, GNU CC does not compile or link anything; it just prints 
the filename. 

Same as -print-file-name=libgcc.a. 

Like -print-file-name, but searches for a program such as cpp. 
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OPTIMIZATION OPTIONS 

T hese options control various sorts of optimizations: 

-o, -01 Optimize. Optimizing compilation takes somewhat more time, and a lot more memory for a 

large function. 

Without -o, the compiler's goal is to reduce the cost of compilation and to make debugging 
produce the expected results. Statements are independent: If you stop the program with a 
breakpoint between statements, you can then assign a new value to any variable or change the 
program counter to any other statement in the function and get exactly the results you would 
expect from the source code. 

Without -o, only variables declared register are allocated in registers. The resulting compiled 
code is a little worse than produced by PCC without-o. 

With -o, the compiler tries to reduce code size and execution time. 

When you specify -o, the two options-fthread-jumps and -fdeter-pop are turned on. On 
machines that have delay slots, the-fdeiayed-branch option isturned on. For those machines 
that can support debugging even without a frame pointer, the-fomit-frame-pointer option is 
turned on. On some machines other flags may also be turned on. 

-02 Optimizeeven more. Nearly all supported optimizationsthat do not involvea space-speed 

tradeoff are performed. Loop unrolling and function inlining are not done, for example As 
compared to -o, this option increases both compilation time and the performance of the 
generated code. 

-03 Optimize yet more. This turns on everything -02 does, along with also turning on -f inline- 

functions. 

-00 Do not optimize. 

If you use multiple -0 options, with or without level numbers, the last such option is the one 
that is effective. 

Options of the form -f flag specify machine-independent flags. M ost flags have both positive and negative forms; the 
negative form of -ftoo would be -tno-f 00 . The following list shows only one form— the one which is not the default. You 
can figure out the other form by either removing no- or adding it. 

-ftioat-store Do not store floating-point variables in registers. This prevents undesirable excess precision on 

machines such asthe 68000 where thefloating registers (of the 68881) keep more precision 
than a double is supposed to have. 

For most programs, the excess precision does only good, but a few programs rely on the precise 
definition of IEEE floating point. Use -ftioat-store for such programs. 

-tmemorize-iookups U se heuristics to compilefaster (C-H-only). These heuristics are not enabled by default, 

-f save-memorized si nee they are only effective for certain input files. Other input files compile more slowly. 

The first time the compiler must build a call to a member function (or reference to a data 
member), it must (1) determine whether the class implements member functions of that name; 
(2) resolve which member function to call (which involves figuring out what sorts of type 
conversions need to be made); and (3) check the visibility of the member function to the caller. 
All of this adds up to slower compilation. N ormally, the second time a call is made to that 
member function (or reference to that data member), it must go through the same lengthy 
process agai n. T h is means that code I i ke th is: 
cout « "This " « p « "has"« \ « " legs.\n" 

makes six passes through all three steps. By using a software cache, a hit significantly reduces 
this cost. U nfortunately, using the cache introduces another layer of mechanisms which must 
be implemented, and so incursitsown overhead, -fmemorize- lookups enables the software 
cache. 

Because access privileges (visibility) to members and member functions may differ from one 
function context to the next, g++ may need to flush the cache. W ith the -fmemorize-iookups 
flag, the cache is flushed after every function that is compiled. The -tsave-memorized flag 
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-fno-default-inline 

-fno-defer-pop 

-fforce-mem 

-fforce-addr 

-fomit-frame-pointer 


-finline-functions 


-fcaller-saves 


-fkeep-inline-functions 

-fno-function-cse 

-fno-peephole 
-ffast-math 


enables the same software cache, but when the compi ler determi nes that the context of the last 
function compiled would yield the same access privileges of the next function to compile it 
preserves the cache. T his is most helpful when defining many member functions for the same 
class: with the exception of member functions which are friends of other classes, each member 
function has exactly the same access privileges as every other, and the cache need not be flushed. 
D on't make member functions inline by default merely because they are defi ned inside the class 
scope (C++only). 

Always pop the arguments to each function call as soon as that function returns. For machines 
which must pop arguments after a function call, the compi ler normally lets arguments 
accumulate on the stack for several function calls and pops them all at once. 

Force memory operands to be copied into registers before doing arithmetic on them. This may 
produce better code by making all memory references potential common subexpressions. W hen 
they are not common subexpressions, instruction combination should eliminate the separate 
register-load. I am interested in hearing about thedifferencethismakes. 

Force memory address constants to be copied into registers before doing arithmetic on them. 
This may produce better codejust as -fforce-mem may. I am interested in hearing about the 
difference this makes. 

Don't keep the frame pointer in a register for functions that don't need one. This avoids the 
instructions to save, set up and restore frame pointers; it also makes an extra register available in 
many functions. It also makes debugging impossibleon most machines. 

On somemachines, such astheVAX, thisflag has no effect because the standard calling 
sequence automatically handles the frame pointer and nothing is saved by pretending it doesn't 
exist. The machine-description macro frame_pointer_required controls whether a target 
machine supports thisflag. 

Integrate all simple functions into their callers. The compi ler heuristi cally decides which 
functions are simpleenough to be worth integrating in thisway. 

If all calls to a given function are integrated, and the function is declared static, then gcc 
normally does not output the function as assembler code in its own right. 

Enablevaluesto be allocated in registers that will be clobbered by function calls, by emitting 
extra instructions to save and restore the registers around such calls Such allocation isdone 
only when it seems to result in better code than would otherwise be produced. 

Thisoption is enabled by default on certain machines, usually those which have no call- 
preserved registers to use instead. 

Even if all calls to agiven function are integrated, and thefunction is declared static, 
nevertheless output a separate runtime callable version of the function. 

Do not put function addressesin registers; make each instruction that calls a constant function 
contain the function's address explicitly. 

Thisoption results in less efficient code, but some strange hacks that alter theassembler output 
may be confused by theoptimizations performed when thisoption isnotused. 

D isableany machine-specific peepholeoptimizations. 

Thisoption allows gcc to violate some AN SI or IEEE specifications in the interest of optimiz¬ 
ing code for speed. For example, it allows the compi ler to assume arguments to thesqrt 
function are nonnegative numbers. 

Thisoption should never be turned on by any-o option because it can result in incorrect 
output for programs which depend on an exact implementation of IEEE or AN SI rules/ 
specificationsfor math functions. 


The following options control specific optimizations The -02 option turns on all of these optimizations except -tunroii- 
loops and -funroll-all-loops. 

The-o option usually turns on the-f thread-jumps and -tdeiayed-branch options but specific machines may change the 
default optimizations. 
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You can use the following flags in the rare cases when fine-tuning of optimizations to be performed is desired: 

-f strength-reduce Perform the optimizations of loop strength reduction and elimination of iteration variables. 

-t thread-jumps Perform optimizations where we check to see if a jump branches to a location where another 

comparison subsumed by the first isfound. If so, the first branch is redi rected to either the 
destination of the second branch or a point immediately following it, depending on whether 
the condition is known to be true or false. 

-t unroii-ioops Perform the optimization of loop unrolling. This is only done for loops whose number of 

iterations can be determined at compiletimeor runtime. 

-t unroii-aii-ioops Perform the optimization of loop unrolling. Thisisdonefor all loops. This usually makes 

programs run more slowly. 

-fcse-foiiow-jumps In common subexpression elimination, scan through jump instructionswhen the target of the 

jump is not reached by any other path. For example, when CSE encounters an if statement 
with an else clause, CSE will follow the jump when the condition tested is false, 
-fcse-skip-biocks This issimilar to -fcse-foiiow-jumps, but causesCSE to followjumps which conditionally skip 

over blocks. When CSE encounters a simple if statement with no else clause, -fcse-skip- 
biocks causes C SE to follow thejump around the body of the if. 

-f rerun-cse-after-ioop Rerun common subexpression elimination after loop optimizations has been performed, 

-feiide-constructors Elide constructors when this seems plausible (C ++ only). With thisflag, GNU C++initializes y 

directly from the call to foo without going through a temporary in the following code 
A foo (); A y =foo (); 

Without this option, GNU C++first initializes y by cal ling the appropriate constructor for type 
A; then assigns the result of foo to a temporary; and, finally, replaces the initial value of y with 
the temporary. 

The default behavior (-fno-eiide-constructors) is specified by the draft AN SI C++standard. If 
your program's constructors have side effects, using -feiide-constructors can make your 
program act differently, si nee some constructor callsmay be omitted. 

-fexpensive-optimizations Perform a number of minor optimizations that are relatively expensive. 

-fdeiayed-branch If supported for the target machine, attempt to reorder instructions to exploit instruction slots 

available after delayed branch instructions. 

-fscheduie-insns If supported for the target machine, attempt to reorder instructions to eliminate execution stalls 

due to required data being unavailable This helps machines that have slow floating point or 
memory load instructions by allowing other instructions to be issued until the result of the load 
or floating point instruction is required. 

-fscheduie-insns 2 Similar to -fscheduie-msns, but requests an additional passof instruction scheduling after 

register allocation has been done. This is especially useful on machines with a relatively small 
number of registers and where memory load instructions take more than one cycle. 

TARGET OPTIONS 

By default, GN U CC compiles code for the same type of machine that you are using. 

However, it can also be i nstalled as a cross-compiler, to compile for some other type of machine. In fact, sa/eral different 
configurations of GN U CC, for different target machines, can be installed side by side. Then you specify which one to use 
with the-b option. 

In addition, older and newer versions of GN U CC can be installed side by side. One of them (probably the newest) will be 
the default, but you may sometimes want to use another. 

-b machine T he argument mac hi ne specifies the target machinefor compi lation. T his is useful when you 

have installed GNU CC as a cross-compiler. 

Thevalueto usefor machi ne is the same as was specified asthemachinetypewhen configuring 
GNU CC as a cross-compiler. For example, if a cross-compiler was configured with configure 
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FI 

i386v, meaning to compile for an 80386 running System V, then you would specify -b i386v to 
run that cross compiler. 

When you do not specify -b, it normally means to compile for the same type of machine that 
you are using. 

-v version T he argument ver s i on specifies which version of GN U CC to run. This is useful when multiple 

versions are installed. For example, version might be 2 . 0 , meaningto run GN U CC version 
2 . 0 . 

The default version, when you do not specify-v, is controlled bytheway GNU CC is installed. 

N ormally, itwill bea version that isrecommended for general use. 


MACHINE-DEPENDENT OPTIONS 


Each of the target machine types can have its own special options, starting with -m, to choose among various hardware 
models or configurations—for example, 68010 versus 68020, floating coprocessor or none. A single installed version of the 
compiler can compilefor any model or configuration, according to theoptionsspecified. 

Some configurations of the compiler also support additional special options, usually for command-line compatibility with 
other compilers on the same platform. 


These are the-m options defined for the 68000 series: 


-m68000 

-mc68000 

-m68020 

-mc68020 

-m68881 

-m68030 

-m68040 

-m68020-40 

-mfpa 

-msoft-float 


G enerate output for a 68000. This is the default when the compiler is configured for 68000- 
based systems. 

G enerate output for a 68020 (rather than a 68000). This is the default when the compiler is 
configured for68020-based systems. 

G enerate output containing 68881 instructions for floating point. This is the default for most 
68020-based systems unless -ntp was specified when the compiler was configured. 

G enerate output for a 68030. This is the default when the compiler is configured for 68030- 
based systems. 

G enerate output for a 68040. This is the default when the compiler is configured for 68040- 
based systems. 

Generate output for a 68040, without using any of the new instructions. Thisresultsin code 
which can run relatively efficiently on either a 68020/68881 or a 68030 or a 68040. 

G enerate output containing Sun FPA instructions for floating point. 

G enerate output containing library callsfor floating point. 


WARNING 


The requisite libraries are not part of GN U CC. N ormally, the facilities of the machine's usual C compiler are used, but 
this can't be done directly in cross-compilation. You must makeyour own arrangements to provide suitable library func¬ 
tions for cross-compilation. 


-mshort 

-mnobitfield 

-mbitfield 


-mrtd 


Consider type int to be 16 bits wide, like short int. 

Do not use the bit-field instructions. -11168000 implies -mnobitfield. 

Do use the bit-field instructions. -11168020 implies -mbitfield. This is the default if you use the 
unmodified sources. 

Use a different function-calling convention, in which functions that take a fixed number of 
arguments return with thertd instruction, which pops their arguments while returning. This 
saves one instruction in the caller si nee there is no need to pop the arguments there. 

This calling convention is incompatible with the one normally used on U NIX, so you cannot 
use it if you need to call libraries compiled with the UN IX compiler. 
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Also, you must provide function prototypes for all functions that take variable numbers of 
arguments (includi ng printf ); otherwise incorrect codewill be generated for calls to those 
functions 

In addition, seriously incorrect code will result if you call a function with too many arguments. 
(N ormally, extra arguments are harmlessly ignored.) 

T he rtd instruction is supported by the 68010 and 68020 processors but not by the 68000. 
These-m optionsaredefined fortheVAX: 

-munix D o not output certai n jump instructions (aobieq and so on) that the UN IX assembler for the 

VAX cannot handleacross long ranges. 

-mgnu D o output those jump instructions on the assumption that you will assemble with theGN U 

assembler. 

-mg Output codeforg-format floating-point numbers instead of d-format. 

These-m switches are supported on the sparc: 

-mfpu G enerate output containing floating-point instructions. This is the default. 

-mhard-float 

-mno-fpu G enerate output containing library callsforfloating point. 

-msoft-float 


WARNING 


There is no GN U floating-point library for SPARC. Normally, the facilities of the machine's usual C compiler are used, 
but this cannot be done directly in cross-compilation. You must make your own arrangements to provide suitable library 
functions for cross-compilation. 


-msoft-float 

-mno-epilogue 

-mepilogue 


-mno-v8 

-mv8 

msparclite 


-mcypress 

-msupersparc 


Changes the calling convention in the output file; therefore it isonly useful if you compi lea// 
of a program with this option. 

With -mepilogue (the default), the compiler always emits code forfunction exit at the end of 
each function. Any function exit in the middle of the function (such as a return statement in C) 
will generate a jump to the exit code at the end of the function. W ith -mno-epiiogue, the 
compiler tries to emit exit code inline at every function exit. 

These three options select variations on the SPARC architecture. By default (unless specifically 
configured for the Fujitsu SPARC lite), gcc generates code for thev7 variant of the SPARC 
architecture. 

-mv8 will give you SPARC v8 code. The only difference from v7 code is that the compiler emits 
the integer multiply and integer divide instructions that exist in SPARC v8 but not in SPARC v7. 
-msparclite will giveyou SPARC lite code. This adds the integer multiply, integer divide step 
and scan (fts) instructions that exist in SPARCIitebut not in SPARC v7. 

T hese two options select the processor for which the code is optimized. 

With -mcypress (the default), thecompiler optimizes code for the Cypress CY7C 602 chip, as 
used in theSparcStation and SparcServer 3xx series. This is also appropriate for the older 
SparcStation 1, 2, IPX, and so on. 

With -msupersparc thecompiler optimizes code for the SuperSparc cpu, as used in the 
SparcStation 10,1000, and 2000 series. Thisflag also enables use of the full SPARC v8 
instruction set. 


These-m optionsare defined fortheConvex: 

-mci G enerate output for a Cl. This is the default when thecompiler is configured for a Cl. 

-mc 2 G enerate output for a C 2. This is the default when thecompiler is configured for a C 2. 
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-margcount G enerate code which puts an argument count in the word preceding each argument list. Some 

nonportable Convex and VAX programs need thisword. (Debuggers don't, except for 
functions with variable-length argument lists; this information isin thesymbol table.) 
-mnoargcount 0 mit the argument count word. This is the default if you use the unmodified sources. 


These-m options are defined fortheAM D Am29000: 


-mdw 

-mnodw 

-mbw 

-mnbw 

-msmall 


-mlarge 

-m29050 

-m29000 

-mkernel-registers 


-muser-registers 

-mstack-check 


Generate code that assumes the DW bit is set, that is, that byte and half-word operations are 
directly supported by the hardware. T his is the default. 

G enerate code that assumes the D W bit is not set. 

Generate code that assumes the system supports byte and halfword write operations. This is the 
default. 

G enerate code that assumes the systems does not support byte and halfword write operati ons. 
This implies -mnodw. 

Useasmall memory model that assumes that all function ad dresses are either with in asingle 
256KB segment or at an absolute address of less than 256K. This allows the can instruction to 
be used instead of a const, consth, cam sequence. 

Do not assume that the can instruction can beused; this isthe default. 

Generate code for theAm29050. 

Generate code for the A m29000. This is the default. 

G enerate references to registersgr64-gr95 instead of gr96- gn 27 . T his option can beused when 
compiling kernel code that wants a set of global registers disjoint from that used by user-mode 
code. 

N ote that when this option is used, register names in -f flags must use the normal, user-mode, 
names. 

Use the normal set of global registers, gr96-gri27. Thisisthe default. 

Insert a call to msp check after each stack adjustment. This is often used for kernel code. 


These-m options are defined for M otorola 88K architectures: 


-m88000 


Generate code that works well on both them88100 and them88110. 


-m88100 
-m88110 

-midentify-revision 

-mno-underscores 

-mcheck-zero-division 

-mno-check-zero-division 


-mocs-debug-info 

-mno-ocs-debug-info 


-mocs-frame-position 
-mno-ocs-frame-position 

-moptimize-arg-area 

-mno-optimize-arg-area 


Generate code that works best forthem88100, but that also runs on them88110. 

Generate code that works best forthem88110, and may not run on them88100. 

Include an ident directive in the assembler output recording the source filename, compiler 
nameand version, timestamp, and compilation flags used. 

In assembler output, emitsymbol nameswithout adding an underscore character at the 
beginning of each name. The default isto use an underscore as prefix on each name. 

Early models of the 88K architecture had problemswith division by zero; in particular, many of 
them didn't trap. Use these options to avoid including (or to include explicitly) additional code 
to detect division by zero and signal an exception. All gcc configurations for the 88K use 
-mcheck-zero-division by default. 

Include (or omit) additional debugging information (about registers used in each stack frame) 
as specified inthe880pen Object Compatibility Standard, OCS. Thisextra information isnot 
needed by GD B. The default for DG/UX, SVr4, and Delta 88 SVr3.2 isto include this 
information; other 88K configurationsomitthisinformation by default. 

Force(ordo not require) register values to be stored in a particular place in stack frames, as 
specified in OCS. The DG/UX, D elta88 SVr3.2, and BCS configurations use -mocs-frame- 
position; other 88K configurations have the default -mno-ocs- frame-position. 

Control howto store function arguments in stack frames, -moptimize-arg-area saves space, but 
may break some debuggers (not GD B). -mno-optimize-arg-area conforms better to standards. 
By default gcc does not optimize the argument area. 
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-mshort-data-num 


-mserialize-volatile 
-mno-serialize-volatile 


-msvr4, -msvr3 


-mtrap-large-shift 
-mhandle-large-shift 
-muse-div-instruction 

-mversion-03.00 


-mwarn-passed-structs 


Generate smaller data references by making them relative to ro, which allows loading a value 
using a single instruction (rather than the usual two). You control which data references are 
affected by specifying num with thisoption. For example, if you specify -mshort-data- 512 , 
then the data references affected are those involving displacements of less than 512 bytes, 
-mshort-data-num is not effective for n u m greater than 64K. 

Do, or do not, generate code to guarantee sequential consistency of volatile memory references. 
GNU CC always guarantees consistency by default, for the preferred processor submodel. How 
this is done depends on the submodel. 

T he m88100 processor does not reorder memory references and so always provides sequential 
consistency. If you use-mssioe, G N U CC does not generate any special instructions for 
sequential consistency. 

T he order of memory references made by the m88110 processor does not always match the 
order of the instructions requesting those references. In particular, a load instruction may 
execute before a preceding store instruction. Such reordering violates sequential consistency of 
volatile memory references, when there are multiple processors. When you use-msseac or 
-m88i 10 , GN U CC generates special instructionswhen appropriate, to force execution in the 
proper order. 

T he extra code generated to guarantee consistency may affect the performance of your 
application. If you know that you can safely forgo this guarantee, you may use the option 
-mno-serialize-volatile. 

Ifyou usethe-m 88 i 00 option but require sequential consistency when running on the m88110 
processor, you should USe-mserialize-volatile. 

T urn on (-msvr4) or off (-msvr3) compiler extensionsrelated to System V release4 (SVr4). This 
controls the following: 

Which variant of the assembler syntax to emit (which you can select independently using 
-mversion-03.00). 

-msvr4 makes the C preprocessor recognize #pragma weak. 

-msvr4 makes gcc issue additional declaration directives used in SVr4. 

-msvr3 is the default for all m88K configurations except the SV r4 configuration. 

Include code to detect bit-shifts of more than 31 bits; respectively, trap such shifts or emit code 
to handle them properly. By default, gcc makes no special provision for large bit shifts. 

V ery early models of the 88K architecture didn't have a divide instruction, so gcc avoids that 
instruction by default. Use thisoption to specify that it’s safe to usethe divide instruction. 

In theDG/UX configuration, there are two flavorsof SV r4. Thisoption rnodifies-msvr4 to 
select whether the hybrid-C OFF or real-ELF flavor is used. All other configurations ignore this 
option. 

Warn when a function passes a struct as an argument or result. Structure-passing conventions 
have changed during the evolution of the C language, and are often the source of portability 
problems. By default, gcc issues no such warning. 


These options are defined for the IB M RS6000: 

-mtp-in-toc Control whether or not floating-point constants go in the table of contents (TOC), atableof 

-mno-fp-in-toc all global variableand function addresses. By default gcc puts floating-point constants there; if 

theTOC overflows, -mno-fp-in-toc will reduce the size of theTOC, which may avoid the 
overflow. 


These -m options are defined for the IBM RT PC: 


-min-line-mul 

-mcall-lib-mul 

-mfull-fp-blocks 


Use an inline code sequence for integer multipl is. This is the default. 

Call imui$$ for integer multiples. 

Generate full-size floating-point data blocks, including the minimum amount of scratch space 
recommended by IBM . T his is the default. 
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-mminimum-fp-blocks 
-mfp-arg-in-fpregs 

-mfp-arg-in-gregs 

-mhc-struct-return 

-mnohc-struct-return 


Do not include extra scratch space in floating-point data blocks. This results in smaller code, 
but slower execution, since scratch space must be allocated dynamically. 

U se a calling sequence incompatible with the IBM calling convention in which floating-point 
arguments are passed in floating-point registers. N otethat varargs.h and stdargs.h will not 
work with floating-point operands if thisoption isspecified. 

Use the normal calling convention for floating-point arguments. This is the default. 

Return structures of more than one word in memory, rather than in a register. This provides 
compatibility with theM etaWareH ighC (he) compiler. Use-fpcc-struct-return for compat¬ 
ibility with thePortableC Compiler (PCC). 

Return some structures of more than one word in registers, when convenient. This is the 
default. For compatibility with the IBM -supplied compilers, use either -fpcc-struct-return or 
-mhc-struct-return. 


These-m optionsare defined for theM IPSfamily of computers: 


-mcpu=c pu- type 


-mips2 

-mips3 

-mint64, -mlong64 

-mlonglong128 

-mmips-as 


-mgas 

-mrnames, -mno-rnames 

-mgpopt, -mno-gpopt 

-mstats, -mno-stats 

-mmemepy, -mno-memepy 

-mmips-tfile 

-mno-mips-tfile 

-msoft-float 


Assume the defaults for the machine type epu-type when scheduling instructions The default 
epu -1 ype is default, which picks the longest cycles times for any of themachines, in order that 
thecoderun at reasonable rates on all M IPSCPUs Other choices for c pu -1 y pe arer 2000 , r3O00, 
r4000,and r 60 O 0 . W hile picking a specific epu- type will schedule things appropriately for that 
particular chip, the compiler will not generate any code that does not meet level 1 of theM IPS 
ISA (instruction set architecture) with-out the-mips 2 or-mips3 switches being used. 

Issue instructions from level 2 of theM IPS ISA (branch likely, square root instructions). 

T he -mcpu=r4000 or -mcpu=r 6000 switch must be used in conjunction with -mips 2 . 

Issue instructions from level 3 of theM IPS ISA (64-bit instructions). The-mcpu=r4O00 switch 
must be used in conjunction with -mips 2 . 

T hese options don't work at present. 

Generate code for theM IPS assembler, and invoke mips-tfiie to add normal debug informa¬ 
tion. Thisisthedefault for all platforms except for the OSF/1 reference platform, using the 
OSF/rose object format. If any of the-ggdb, -gstabs, or-gstabs+ switches are used, themips- 
tfiie program will encapsulate the stabs with in M IPS ECOFF. 

G enerate code for theGN U assembler. This is the default on the OSF/1 reference platform, 
usi ng the 0 SF/rose object format. 

The -mrnames switch saysto output code using theM IPS software names for the registers, 
instead of the hardware names (for example a0 instead of $ 4 ). T he G N U assembler does not 
support the -mrnames switch, and theM IPS assembler will be instructed to run theM IPS C 
preprocessor over the source file. The -mno-rnames switch is default. 

The -mgpopt switch saysto write all of the data declarations before the instructions in the text 
section, to all theM IPS assembler to generate one-word memory references i nstead of using 
two words for short global or static data items. This is on by default if optimization is selected. 
For each noninlinefunction processed, the-mstats switch causes the compiler to emitoneline 
to the standard error file to print statistics about the program (number of registers saved, stack 
size, and so on). 

The -mmemepy switch makes all block moves call the appropriate string function (memepy or 
bcopy) instead of possibly generating inlinecode. 

The -mno-mips-tfiie switch causes the compiler to not post-process the object file with the 
mips-tfiie program, after theM IPS assembler has generated it to add debug support. If mips- 
tfiie isnot run, then no local variables will be availableto thedebugger. In addition, stage 2 
and stage3 objects will have the temporary filenames passed to the assembler embedded in the 
object file, which meanstheobjectswill not compare the same. 

G enerate output containing library calls for floating point. 
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WARNING 


The requisite libraries are not part of GN U CC. N ormally, the facilities of the machine's usual C compiler are used, but 
this can't be done directly in cross-compilation. You must makeyour own arrangements to provide suitable library func¬ 
tions for cross-compi lati on. 


-mhard-float 

-mfp64 


-mfp32 

-mabicalls 

-mno-abicalls 

-mhalf-pic 

-mno-half-pic 

-Gnum 


-nocpp 


G enerate output containing floating point instructions. This is the default if you use the 
unmodified sources. 

Assume that the fr bit in the status word is on, and that there are 32 64-bit floating-point 
registers, instead of 32 32-bit floating-point registers. You must also specify the-mcpu=r4000 and 
-mips3 switches. 

Assume that there are 32 32-bitfloating-point registers. This isthe default. 

Emit (or do not emit) the .abicaiis, .cpioad, and .cprestore pseudo operations that some 
System V.4 ports use for position-independent code. 

T he -mhaif-pic switch says to put pointers to extern references into the data section and load 
them up, rather than put the references in the text section. This option does not work at 
present. 

Put global and static items less than or equal to num bytes into the small data or bss sections 
instead of the normal data or bss section. This allows the assembler to emit one-word memory 
reference instructions based on the global pointer (gp or $ 28 ), instead of the normal two words 
used. By default, num is 8 when the MIPS assembler is used, and 0 when theGN U assembler is 
used. The -Gnum switch isalso passed to theassembler and linker. All modules should be 
compiled with thesarne-Gnum value. 

Tell the M IPS assembler to not run its preprocessor over user assembler files (with an . s suffix) 
when assembling them. 


These-m options are defined for the I ntel 80386 family of computers: 

-m486, -mno-486 Control whether or notcodeisoptimized fora486 instead of a386. Codegenerated fora486 

wi 11 ru n on a 386 and vi ce versa. 

-msott-fioat G enerate output containing library callsfor floating point. 


WARNING 


The requisite libraries are not part of GN U CC. N ormally, the facilities of the machine's usual C compiler are used, but 
this can't be done directly in cross-compilation. You must makeyour own arrangements to provide suitable library func¬ 
tions for cross-compi lati on. 


On machines where a function returns floating point results in the 80387 register stack, some 
floating-point opcodes may be emitted even if -msoft-float isused. 

-mno-fp-ret-in-387 D o not use the FPU registers for return values of functions. 

Theusual calling convention has functions return values of types float and doublein an FPU 
register, even if there is no FPU. The idea isthat the operating system should emulate an FPU. 
Theoption -mno-fp-ret-in-387 causes such values to be returned in ordinary CPU registers 
instead. 

These-m options are defined for the FI PPA family of computers: 

-mpa-risc-i -0 G enerate code for a PA 1.0 processor. 

-mpa-risc-i -i G enerate code for a PA 1.1 processor. 
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-mkernel 

-mshared-libs 

-mno-shared-libs 

-mlong-calls 

-mdisable-fpregs 

-mdisable-indexing 
-mtrailing-colon 


Generate codewhich is suitable for use in kernels. Specifically, avoid add instructions in which 
one of the arguments is the D P register; generate addii i nstructions instead. T his avoids a rather 
serious bug in theH P-UX linker. 

Generate code that can be linked against H P-UX shared libraries. This option is not fully 
functioning yet, and is not on by default for any PA target. Using this option can cause 
incorrect codeto be generated by the compiler. 

Don't generate code that will belinked against shared libraries. Thisisthe default for all PA 
targets. 

Generate codewhich allows calls to functions greater than 256K away from the caller when the 
caller and callee are i n the same source file. Do not turn thisoption on unless code refuses to 
link with branch out of range errors from the linker. 

Prevent floating-point registers from being used in any manner. This is necessary for compiling 
kernels that perform lazy context switching of floating-point registers. If you use thisoption 
and attempt to perform floating-point operations the compi ler will abort. 

Prevent the compiler from using indexing address modes. T his avoids some rather obscure 
problems when compiling M IG-generated code under MACH. 

Add a colon to theend of label definitions (for ELF assemblers). 


These-m options are defined for the Intel 80960 family of computers: 


-me p u -1 y p e 

-mnumerics 
-msoft-float 
-mleaf-procedures 
-mno-leaf-procedures 


-mtail-call 

-mno-tail-call 


-mcomplex-addr 

-mno-complex-addr 


-mcode-align 

-mno-code-align 

-mic-compat 

-mic2.0-compat 

-mic3.0-compat 

-masm-compat 

-mintel-asm 

-mstrict-align 

-mno-strict-align 

-mold-align 


Assume the defaults for the machine type epu-type for instruction and addressing-mode 
availability and alignment. The default c pu- type is kb; other choices are ka, me, ca, ct, sa, and sb. 
T he -mnumerics option indicates that the processor does support floati ng-point instructions. 

T he -msoft-fioat option indicates that floati ng-point support should not be assumed. 

Do (or do not) attempt to alter leaf procedures to be callable with thebai instruction as well as 
cai i . This will result in more efficient code for explicit calls when thebai instruction can be 
substituted by the assembler or linker, but less efficient code in other cases, such as calls via 
function pointers, or using a linker that doesn't support this optimization. 

Do(ordo not) make additional attempts (beyond thoseof the machine-independent portions 
of the compi ler) to optimize tail-recursive calls into branches. You may not want to do this 
because the detection of cases where this is not valid is not totally complete. T he default is 
-mno-tail-call. 

Assume (or do not assume) that the use of a complex addressing mode is a win on this imple¬ 
mentation of the i960. Complex addressing modes may not be worthwhile on the K-series, but 
they definitely are on the C-series. The default is currently -mcompiex-addr for all processors 
except theCB and CC. 

Align codeto 8-byte boundaries for faster fetching (or don't bother). Currently turned on by 
default for C-series implementations only. 

Enablecompatibility with iC 960 v2.0 or v3.0. 


E nable compatibi lity with the iC 960 assembler. 

D o not permit (do permit) unaligned accesses. 

Enable structure-alignment compatibility with Intel's gcc release version 1.3 (based on gcc 
1.37). Currently this is buggy in that #pragma align i isalways assumed as well, and cannot be 
turned off. 
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These-m options are defined fortheD EC Alpha implementations: 

Usefdo not use) the hardware floating-poi nt i nstructions for floating-point operations. When 
-msoft-float is specified, functionsin libgcci .c will be used to perform floating-point 
operations. Unless they are replaced by routines that emulate thefloating-point operations, or 
compiled in such away as to call such emulations routines, these routines will issuefloating- 
point operations. If you are compiling for an Alpha without floating-point operations, you 
must ensure that thelibrary is built so as not to call them. 

N ote that Alpha implementations without floating-point operations are required to have 
floating-point registers. 

Generate code that uses (does not use) thefloating-point register set. -mno-fp-regs implies 
-msoft-float. If thefloating-point register set is not used, floating-point operands are passed in 
integer registers as if they were integers and floating-point results are passed in $0 instead of $to. 
This is a nonstandard calling sequence so any function with a floating-point argument or 
return value called by codecompiled with -mno-fp-regs must also be compiled with that 
option. 

A typical useof thisoption is building a kernel that does not use, and hence need not save and 
restore, any floating-point registers. 

These additional options are available on System V Release 4 for compatibility with other compilers on those systems: 

-g On SVr4 systems, gcc accepts the option -g (and passes it to the system linker), for compatibil¬ 

ity with other compilers. H owever, we suggest you use -symbolic or -shared as appropriate, 
instead of supplying linker options on thegcc command line. 

-Qy Identify the versions of each tool used by the compiler, in an .ident assembler directive in the 

output. 

-on Refrain from adding .ident directives to theoutput file (this isthe default). 

-yp.di r s Search the directories di rs, and no others, for libraries specified with - 1 . You can separate 

directory entriesin di rs from one another with colons. 

-Ym,di r Look in the directory di r to find theM 4 preprocessor. The assembler uses this option. 

CODEGENERATION OPTIONS 

These machine-independent options control the interface conventions used in codegeneration. 

M ostof them begin with -f. These options have both positive and negative forms; the negative form of-ffoo would be-fno- 
foo. In the following table, only one of the forms is listed—the one which is not the default. You can figure out the other 
form by either removing no- or adding it. 

-f nonnuii-objects Assume that objects reached through references are not null (C++only). 

Normally, GNU C++makes conservative assumptions about objects reached through 
references. For example, the compiler must check that a is not null in code I ike the following: 

obj &a = g (); a.f (2); 

C hacking that references of this sort have nonnull values requires extra code, however, and it is 
unnecessary for many programs. You can use -fnonnuii-objects to omit the checks for null, if 
your program doesn't require checking. 

-fpcc-struct-return U se the same convention for returning struct and union values that is used by the usual C 

compiler on your system. This convention is less efficient for small structures, and on many 
machines it fails to be reentrant; but it has the advantage of allowing internal lability between 
gee-compiled code and pcc-compiled code. 

-freg-struct-return U se the convention that struct and union values are returned in registerswhen possible. This is 

more efficient for small structures than -fpcc-struct-return. 

If you specify neither -fpcc-struct-return nor -freg-struct-return, GN U CC defaults to 
whichever convention is standard for the target. If there is no standard convention, GNU CC 
defaults to -fpcc-struct-return. 


-mno-soft-float 

-msoft-float 


-mfp-reg, -mno-fp-regs 
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-fshort-enums 

-fshort-double 

-fshared-data 

-fno-common 

-fno-ident 

-fno-gnu-linker 

-finhibit-size-directive 

-fverbose-asm 

-fvolatile 

-fvolatile-global 

-fpic 

-fPIC 

-ffixed-r eg 

-fcall-used-r eg 

-fcall-saved-r eg 



Allocate to an enum type only as many bytes as it needs for the declared range of possible values. 
Specifically, the enum type will be equivalent to the smallest integer type that has enough room. 

U se the same size for double as for float. 

Requests that the data and non-const variables of this compilation be shared data rather than 
private data. The distinction makes sense only on certain operating systems, where shared data 
isshared between processes running the same program, while private data exists in onecopy per 
process. 

Allocate even uninitialized global variables in thebss section of the object file rather than 
generating them as common blocks. T his has the effect that if the same variable is declared 
(without extern) in two different compilations, you will get an error when you link them. The 
only reason this might be useful is if you want to verify that the program will work on other 
systems which always work this way. 

Ignore the #ident directive. 

Do not output global initializations (such as C++constructors and destructors) in theform 
used by theGN U linker (on systems where the GN U linker is the standard method of handling 
them). Use this option when you want to use a non-GN U linker, which also requires using the 
coiiect 2 program to make sure the system linker includes constructors and destructors 
(coiiect 2 isincluded in the GNU CC distribution.) For systems that must use coiiect 2 , the 
compiler driver gcc isconfigured to do this automatically. 

Don't output a .size assembler directive, or anything else that would cause trouble if the 
function issplit in themiddle, and thetwo halves are placed at locations far apart in memory. 
This option is used when compiling crtstuff.c; you should not need to use it for anything else. 
Put extra commentary information in the generated assembly code to make it more readable. 
This option is generally only of use to those who actually neal to read the generated assembly 
code (perhaps while debugging the compiler itself). 

Consider all memory references through pointers to be volatile. 

Consider all memory references to extern and global dataitemsto be volatile. 

If supported for the target machines, generate position-independent code, suitablefor use in a 
shared library. 

If supported for the target machine, emit position-independent code, suitablefor dynamic 
linking, a/en if branches need large displacements 

T reat the register named r eg as a fixed register; generated code should never refer to it (except 
perhaps as a stack pointer, frame pointer, or in some other fixed role), 
r eg must be the name of a register. The register names accepted are machine-specific and are 
defined in the register_names macro in the machine description macro file. 

T his flag does not have a negative form, because it specifies a three-way choice 
T reat the register named r eg as an allocable register that is clobbered by function calls. It may 
be allocated for temporaries or variables that do not live across a call. Functions compiled this 
way will not save and restore the register r eg. 

Use of thisflagfor a register that has a fixed pervasive role in the machine's execution model, 
such asthestack pointer or frame pointer, will produce disastrous results 
T his flag does not have a negative form, because it specifies a three-way choice. 

T reat the register named r eg as an allocable register saved by functions. It may be allocated a/en 
for temporaries or variables that liveacross a call. Functionscompiled thisway will save and 
restore the register r eg if they use it. 

Use of thisflagfor a register that has a fixed pervasive role in the machine's execution model, 
such asthestack pointer or frame pointer, will produce disastrous results. 

A different sort of disaster will result from the use of thisflag for a register in which function 
values may be returned. 

T his flag does not have a negative form, because it specifies a three-way choice. 
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PRAGMAS 

T wo //pragma directives are supported for GN U C++to permit using the same header file for two purposes: as a definition of 
interfaces to a given object class, and as the full definition of the contents of that object class. 


#pragma interface 

(C ++ only.) Use this directive in header files that define object classes, to save space in most of 
the object files that use those classes. N ormally, local copies of certain information (backup 
copies of inline member functions, debugging information, and the internal tables that 
implement virtual functions) must be kept in each object file that includes class definitions. You 
can use this pragma to avoid such duplication. When a header file containing #pragma 
interface is included in acompilation, thisauxiliary information will not be generated (unless 
themain input source file itself uses #pragma implementation). Instead, the object files will 
contain referencesto be resolved at link time. 

#pragma implementation 

(C ++ only.) Use this pragma in a main input file, when you want full output from included 

#pragma implementation 

header files to be generated (and made globally visible). The included header file, in turn, 

"obj ects .h" 

should use #pragma interface. Backup copiesof inline member functions, debugging informa¬ 
tion, and the internal tables used to implement virtual functions are all generated in implemen¬ 
tation files. 

If you use#pragma implementation with no argument, it applies to an include filewith thesame 
basename as your source file; for example, in aiiciass.cc, #pragma implementation by itself is 
equivalent to #pragma i-piementation "aiiciass. h 11 . U se the string argument if you want a 
single implementation file to include code from multiple header files. 

There is no way to split up the contents of a single header file into multiple implementation 
files. 

FILES 

file.c 

C source file 

file.h 

C header (preprocessor) file 

file.i 

Preprocessed C source file 

file.C 

C++source file 

file.cc 

C++source file 

file.cxx 

C++source file 

file.m 

0bjective-C sourcefile 

file.s 

Assembly language file 

file.o 

Object file 

a.out 

Link edited output 

TMPDI R/cc 

T emporary files 

LI BDI R/cpp 

Preprocessor 

LI BDI R/ccl 

Compiler for C 

LI BDI R/cclplus 

Compiler for C++ 

LI BDI R/collect 

Linker front end needed on some machines 

LI BDI R/libgcc.a 

gcc subroutine library 

/lib/crt[01n ].0 

Startup routine 

LI BDI R/ccrt0 

Additional startup routineforC++ 

/lib/libc.a 

Standard C library; seeintro(3) 

/usr/include 

Standard directory for //include files 

LI BDI R/include 

Standard gcc directory for //include files 

LI BDI R/g++-include 

Additional g++directory for //include 


LI B D I R is usually /usr/ local /lib/mac hi ne /versi on. 

tmpdi r comes from theenvironmentvariableiMPDiR (default /usr/tmp if available; otherwise, /trip.). 
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SEE ALSO 

cpp(l), as(l), ld(l), gdb(l), adb(l), dbx(l), sdb(l) 
gcc, cpp, as, Id, and gdb entries in info. 

Using and Porting GNU CC (for version 2.0), Richard M . Stallman; TheC Preprocessor, Richard M . Stallman; Debugging 
with GDB: theGNU Source-Level Debugger, Richard M . Stallman and Roland H. Pesch; Uangas theGNU Assembler, Dean 
Eisner, Jay Fenlason & friends; Id: theGNU Linker, Steve Chamberlain and Roland Pesch. 

BUGS 

For instructionson reporting bugs, seetheGCC manual. 

COPYING 

Copyright 1991,1992,1993 FreeSoftwareFoundation, Inc. 

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this 
permission notice are preserved on all copies. 

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 

Permission is granted to copy and distribute translations of this manual into another language, under the preceding 
conditions for modified versions, except that this permission notice may be included in translations approved by the Free 
Software Foundation instead of in theoriginal English. 

AUTHORS 

SeetheGNU CC manual for the contributors to GNU CC. 

GNU Tools 13 October 1993 
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gemtopbm— Convert a GEM IMG file into a portable bitmap 

SYNOPSIS 

gemtopbm [-d] [ gemfile ] 

DESCRIPTION 

Reads a GEM IMG file as input. Reads from stdin if input file is omitted. Produces a portable bitmap as output. 

OPTIONS 

-d Produce output describing the contents of thelM G file. 

BUGS 

D oes not support files containing more than one plane. 

SEE ALSO 

pbmtogem(l), pbm(5) 

AUTHOR 

Copyright© 1988 DiomidisD. Spinellis(dds@cc.ic.ac.uk). 


11 Julyl992 
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geqn— Format equations for troff 

SYNOPSIS 

geqn [ -rvCNR ][-dcc ][-Tname ] [ -Md i r ] [ -f F ][-sn ] [-pn ] [ -mn ] [files ... ] 

DESCRIPTION 

This manual page describes the GN U version ofeqn, which is part of the groft document formatting system, eqn compiles 
descriptions of equations embedded within troff input files into commands that are understood by troff. N ormally, it 
should be invoked using the -e option of groff. The syntax is quite compatible with U NIX eqn. The output of GN U eqn 
cannot be processed with U N IX troff; it must be processed with GN U troff. If no files are given on the command line the 
standard input will be read. A filename of - will cause the standard input to be read. 

eqn searches for the fi le eqnrc using the path .:/usr/iib/groff/tmaci/usr/iib/tmac. If it exists, eqn will process it before the 
other input files. The -r option prevents this. 

GNU eqn does not provide the functionality of neqn: it does not support low-resolution, typewriter-like devices (although it 
may work adequately for very simple input). 

OPTIONS 

-c Recognize .eq and .en even when followed by a character other than space or newline. 

-n Don't allow newlines within delimiters. This option allows eqn to recover better from missing closing 

delimiters. 

-v Print the version number. 

-r Only one size reduction. 

-mn The minimum point-size is n. eqn will not reduce the size of subscripts or superscripts to a smaller size 

than n. 

-Tname The output is for device name. T he only effect of this is to define a macro name with a value of i. Typically, 

eqnrc will use this to provide definitions appropriate for the output device. The default output device is ps. 
-Mdi r Search dir for eqnrc before the default directories. 

-R D On't load eqnrc. 

-tF T his is equivalent to a gfontF command. 

-sn This is equivalent to agsizen command. This option is deprecated, eqn will normally set equations at 

whatever the current pointsize iswhen theequation is encountered. 

-pn This says that subscripts and superscripts should ben points smaller than the surrounding text. Thisoption 

is deprecated. N ormally, eqn makes sets subscripts and superscripts at 70 percent of the size of the 
surrounding text. 

USAGE 

Only the differences between GNU eqn and UN IX eqn are described here. 

M ost of the new features of G N U eqn are based on T eX. T here are some references to the differences between T eX and 
GNU eqn asfollows; these may safely be ignored if you do not knowTeX. 

AUTOMATIC SPACING 

eqn gives each component of an equation a type, and adjusts the spacing between components using that type. Possible types 


are 


ordinary 

An ordinary character such as i orx 

operator 

A large operator such as; 

binary 

A binary operator such as + 

relation 

A relation such as = 
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opening 

closing 

punctuation 

inner 

suppress 


An opening bracket such as ( 

A closing bracket such as) 

A punctuation character such as, 

A subformula contained within brackets 
Spacing that suppresses automatic spacing adjustment 


Components of an equation get a type in one of two ways: 

typete T his yields an equation component that containse but that has type t, where t is one of the types 

mentioned previously. For example, times is defined as 
type "binary" \(mu 

The name of the type doesn't have to be quoted, but quoting protects from macro expansion, 
chartypettext Unquoted groups of charactersare split up into individual characters, and the type of each character is 
looked up; this changes the type that is stored for each character; it says that the characters in text from 
now on havetypet. For example 

chartype “punctuation" 

would make the characters.have type punctuation whenever they subsequently appeared in an 
equation. The type t can also be letter or digit; in these cases, chartype changes the font type of the 
characters. Seethe "Fonts” section, later in thismanual page. 


NEW PRIMITIVES 

elsmallovere2 

vcentere 

elaccente2 

eluaccente2 

splittext 
nosplitt ext 
eopprime 


specialt ext e 


This is similar to over; smaiiover reduces the size of ei and e 2 ; it also puts less vertical space between e 1 or 
e 2 and the fraction bar. The over primitive corresponds to the\over primitive in display styles; smaiiover 
corresponds to \over in nondisplay styles. 

This vertically centers e about the math axis. The math axis is the vertical position about which characters 
such as+ and - are centered; also it is the vertical position used for the bar of fractions. For example, sum is 
defined as 

{type"operator" vcenter size +5 \(*S} 

T his sets e 2 as an accent over ei. e 2 is assumed to be at the correct height for a lowercase letter; e 2 will be 
moved down according if ei istaller or shorter than a lowercase letter. For example, hat isdefined as 
accent } 

dotdot, dot, tilde, vec, and dyad are also defined using the accent primitive. 

T his sets e 2 as an accent under ei. e 2 isassumed to be at the correct height for a character without a 
descender; e 2 will be moved down if e 1 has a descender, utiide is predefined using uaccent as a tilde accent 
below the baseline. 

This has the same effect as simply text, but text is not subject to macro expansion because it is quoted; 
text will be split up and thespacing between individual characters will be adjusted. 

This has the same effect as text, but because text is not quoted it will be subject to macro expansion; text 
will not besplitup and thespacing between individual characters will not be adjusted. 

T his is a variant of prime that acts as an operator one.lt produces a different result from prime in a case 
such asAopprimesubi : W ith opprime the i will be tucked under the prime as a subscript to the a (as is 
conventional in mathematical typesetting), whereas with prime the i will be a subscript to the prime 
character. The precedence of opprime isthe same as that of bar and under, which is higher than that of 
everything except accent and uaccent. In unquoted text, a 1 that is not thefirst character will be treated 
like opprime. 

This constructs a new object frame using agtroft(l) macro named text . When the macro is called, the 
string os will contain the output fore, and the number registers ow, ah, ad, 0 skern and oskew will contain 
the width, height, depth, subscript kern, and skew of e. (Thesubscript kern of an object says how much a 
subscript on that object should be tucked in; the skew of an object says how far to the right of the center of 
the object an accent over the object should be placed.) The macro must modify es so that it will output 
thedesired result with itsorigin at the current point, and increase the current horizontal position by the 
width of the object. The number registers must also be modified so that they correspond to the result. 
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For example, suppose you wanted a construct that cancels an expression by drawing a diagonal line through it: 

■ EQ 

define cancel 'special Ca' 

.EN 

.de Ca 

.ds 0s \Z , \\*(0s'\v , \\n(0du'\D l l \\n(0wu -\\n(0hu-\\n(0du 1 \v'\\n(0hu 1 

Then you could cancel an expression U with cancel e. 

H ere's a more complicated construct that draws a box around an expression: 

■ EQ 

define box 'special Bx' 

.EN 

.de Bx 

.ds 0s \Z'\h'1n'\\*(0s'\ 

\Z'\v'\\n(0du+1n'\D l l \\n(0wu+2n 0'\D'1 0 -\\n(0hu-\\n(0du-2n'\ 

\D'1 -\\n(0wu-2n 0'\D'1 0 \\n(0hu+\\n(0du+2n"\h'\\n(0wu+2n 1 
.nr 0w +2n 
.nr 0d +1n 
.nr 0h +1n 


CUSTOMIZATION 

T he appearance of equations is controlled by a large number of parameters. T hese can be set using the set command, 
setpn This sets parameter p to value n ; n isan integer. For example 

set x_height 45 

says that eqn should assume an x height of 0.45 ems. 


Possible parameters are as follows. Values are in units of hundredths of an em unless otherwise stated. These descriptions are 
intended to be expository rather than definitive. 


minimum_size 

fat_offset 

over_hang 


accent width 


delimiterjfactor 


delimiter shortfall 


null_delimiter_space 

script_space 

thin_space 

medium_space 

thick_space 


eqn will not set anything at a smaller point size than this. The value is in points. 

Thetat primitive emboldens an equation by overprinting two copies of the equation horizontally 
offset by this amount. 

A fraction bar will belonger by twice thisamount than the maximum of the widths of the 
numerator and denominator; in other words, it will overhang the numerator and denominator by 
at least thisamount. 

When bar or under is applied to a single character, the line will be this long. N ormally, bar or 
under producesalinewhoselength isthe width of the object to which itapplies; in thecaseof a 
single character, thistendsto producea linethat looks too long. 

Extensible delimiters produced with the left and right primitives will have a combined height and 
depth of at least this many thousandths of twice the maxi mum amount by which the subequation 
that the delimiters enclose extends away from the axis. 

Extensible delimiters produced with the left and right primitives will have a combined height and 
depth not less than the difference of twice the maxi mum amount by which the subequation that 
the delimiters enclose extends away from the axis and thisamount. 

This much horizontal space is inserted on each side of a fraction. 

Thewidth of subscripts and superscripts is increased by thisamount. 

Thisamount of space is automatically inserted after punctuation characters. 

Thisamount of space is automatically inserted on either side of binary operators. 

Thisamount of space is automatically inserted on either side of relations. 
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x_height The height of lowercase letters without ascenders such asx. 

axis_height T he height above the baseline of the center of characters such as + and-. It is important that this 

value be correct for the font you are usi ng. 

defauit_ruie_t hickness This should set to the thickness of the \ ( ru character, or the thickness of horizontal lines produced 
withthe\D escape sequence. 

numi The oven command will shift up the numerator by at least this amount. 

num 2 T he smaiiover command will shift up the numerator by at least this amount, 

denomi The oven command will shift down the denominator by at least this amount. 

denom 2 Thesmaiioven command will shift down the denominator by at least this amount, 

supi N ormally superscripts will be shifted up by at least this amount. 

sup 2 Superscripts within superscripts or upper limits or numerators of smaiiover fractions will be shifted 

up by at least this amount. This is usually less than supi. 

sup3 Superscripts within denominators or square roots or subscripts or lower limitswill be shifted up by 

at least this amount. This is usually less than sup 2 . 
subi Subscripts will normally be shifted down by at least thisamount. 

sub 2 When there isboth a subscript and a superscript, the subscript will be shifted down by at least this 

amount. 

sup_drop The baseline of a superscript will be no more than thisamount below the top of the object on 

which the superscript is set. 

sub_drop T he baseli ne of a subscript will be at least this much below the bottom of the object on which the 

subscript is set. 

big_op_spacingi The baseli ne of an upper limitwill beat least thismuch above thetop of theobjecton which the 

limit is set. 

big_op_spacing 2 T he baseli ne of a lower limit will be at least this much below the bottom of the object on which the 

limit is set. 

big_op_spacing3 The bottom of an upper limitwill beat least thismuch above the top of theobjecton which the 

limit is set. 

big_op_spacing4 Thetop of a lower limitwill beat least thismuch below the bottom of the object on which the 

limit is set. 

big_op_spacing5 Thismuch vertical space will be added aboveand below limits. 

baseiine_sep The baselines of therowsin a pile or matrix will normally be this far apart. In most cases, this 

should be equal to the sum of numi and denomi. 

shift_down The midpoint between thetop baseline and the bottom baseline in a matrix or pile will be shifted 

down by this much from the axis. In most cases, this should be equal to axisjieight. 
coiumn_sep Thismuch space will be added between columnsin amatrix. 

matrix_side_sep T his much space will be added at each side of a matrix. 

draw_iines If this is nonzero, lines will be drawn using the \d escape sequence rather than with theu escape 

sequence and the \(ru character. 

body_height T he amount by which the height of the equation exceeds this will be added as extra space before 

the line containing the equation (using \x.) T he default value is 85. 
body_depth T he amount by which the depth of the equation exceeds this will be added as extra space after the 

line containing the equation (using \x.) The default value is 35 . 
nroff If this is nonzero, then ndefine will behave like define and tdefine will be ignored; otherwise, 

tdefine will behave like define and ndefine will be ignored. T he default value is 0 . (This is typically 
changed to 1 by theeqnrc filefor theascii and latini devices.) 

A more precise description of the role of many of these parameters can be found in Appendix H of T/ieTeXbook. 
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MACROS 

M acroscan take arguments. In a macro body, $ n where n is between 1 and 9, will be replaced by the nth argument if the 
macro is cal led with arguments; if there are fewer than n arguments, it will be replaced by nothing. A word containing a left 
parenthesis where the part of the word before the left parenthesis has been defined using thedefine command will be 
recognized as a macro call with arguments characters following the left parenthesis up to a matching right parenthesis will be 
treated as comma-separated arguments; commas inside nested parentheses do not terminate an argument. 

sdefinename xanyt hi ngx T his is like thedefine command, but name will not be recognized if called with arguments, 
inciudef i i e I nclude the contents of f i e. Lines of f i i e beginning with .eq or .en will be ignored, 

ifdetna me xanyt hi ngx If name has been defined by define (or has been automatically defined becausename istheoutput 
device), process a nyt hi n g ; otherwise ignore a n y t hi ng. 
x can be any character not appearing in a nyt hi ng. 


FONTS 

eqn normally uses at least two fonts to set an equation: an italic font for letters, and a Roman font for everything else. The 
existing gtont command changes the font that is used as the italic font. By default this is i. The font that is used as the 
Roman font can be changed by using the new grfont command. 

grfontf Set the Roman font to f . 

The italic primitive uses the current italic font set by gtont; the Roman primitive uses the current Roman font set by grfont. 
There is also a new gbtont command, which changes thefont used by the bold primitive. If you only use the Roman, italic, 
and bold primitives to change fonts within an equation, you can change all the fonts used by your equations just by using 
gtont, grfont, and gbtont commands. 

You can control which characters are treated as letters (and therefore set in italic) by using the chartype command described 
earlier. A type of letter will cause a character to beset in italic type. A type of digit will cause a character to beset in Roman 
type. 

FILES 

/usr/iib/groff/tmac/eqnrc Initialization file 

BUGS 

Inline equationswill beset at the pointsize that is current at the beginning of the input line. 

SEE ALSO 

groff(l), gtroff(l), groff_font(5), TheT eYbOOk 

getlist 

getiist— Get a list from an NNTP server 

SYNOPSIS 

getlist [ -h host ][list [ pattern [ types ]]] 

DESCRIPTION 

The getlist program obtains a list from an N NTP server and sends it to standard output. 

The list may be one Of active, active, times, distributions, Or newsgroups. T hese values request the active(5), 
active.times, /news/lib/distributions, Or /news/lib/newsgroups files, respectively. 

If the-h flag is used, then the program connects to the server on the specified host. The default is to connect to the server 
specified in theinn.cont(5) file. 
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If the list parameter is active, then the pattern and types parameters may be used to limit the output. When pattern is 
used, only active lines with groups that match according to wiidmat(3) are printed. When types is also given, only active lines 
that have a fourth field starting with a character found intypes are printed. 

For example, the following command will obtain the one-line descriptions of all newsgroups found on uunet: 
getlist -h news.uu.net newsgroups 

T he following line lists all groups where local postings are permitted, moderated, or aliased: 
getlist active ym= 

N otethat the listing files other than the active file is a common extension to the N NTP protocol and may not be available 
on all servers. 

HISTORY 

W ritten by Landon Curt N oil (<chongo@toad.com>) for InterN etN ews. 

SEE ALSO 

active(5), nnrpd(8), wildmat(3) 


getopt 

getopt— Parse command options 

SYNOPSIS 

set - 'getopt optstring $*' 


DESCRIPTION 

getopt is used to break up options in command lines for easy parsing by shell procedures, and to check for legal options, 
optstring isastring of recognized option letters; see getopt(3). If a letter is followed by a colon, theoption isexpected to 
have an argument that may or may not be separated from it by whitespace. T he special option - - is used to delimit the end 
of the options, getopt will place -- in the arguments at the end of the options, or recognize it if used explicitly. The shell 
arguments($i $2 ...) are reset so that each option is preceded bya- and in its own shell argument; each option argument 
is also in its own shell argument. 


EXAMPLE 

The following codefragment shows how one might process the arguments for a command that can take the options a and b, 
and theoption 0 , which requires an argument: 


set 


'getopt abo: $*' 
if test $? != 0 
then 

echo 'Usage: . 
exit 2 
fi 

for i 
do 

case "$i" 
in 

-a|-b) 
-0) 


flag=$i; shift;; 
oarg=$2; shift; shift;; 


shift; break;; 


done 


esac 
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This code will accept any of the following as equivalent: 

cmd -aoarg file file 
cmd -a -o arg file file 
cmd -oarg -a file file 
cmd -a -oarg -- file file 

SEE ALSO 

sh( 1), getopt(3) 

DIAGNOSTICS 

getopt prints an error message on the standard error output when it encounters an option letter not included in optstring. 

HISTORY 

W ritten by H enry Spencer, working from a Bell Labs manual page. Behavior believed identical to the Bell version. 

BUGS 

W hatever getopt(3) has. 

Arguments containing whitespace or embedded shell metacharacters generally will not survive intact; this looks easy to fix 
but isn't. 

The error message for an invalid option is identified as coming from getopt rather than from the shell procedure containing 
the invocation of getopt; this, again, is hard to fix. 

The precise best way to use the set command to set the arguments without disrupting the value(s) of shell options varies 
from oneshell version to another. 

21Junel993 


giftopnm 

giftopnm — C onvert a GIF file into a portableanymap 

SYNOPSIS 

giftopnm [-verbose][-comments][-image N ] [Gl FfiI e ] 

DESCRIPTION 

Readsa GIF filefor input, and outputs portable anymap. 

OPTIONS 

-verbose Produces verbose output about the G IF fileinput. 

-comments 0 nly outputs GIF89 comment fields. 

-image 0 utputs the specified GIF image from the input GIF archivefwhereN is i, 2 , 20 ...). Normally, thereis 

only one image per file, so thisoption isnot needed. 

All flags can be abbreviated to their shortest unique prefix. 

BUGS 

This does not correctly handle the P lai n T ext Extension of the GIF89 standard, si nee I did not have any example input files 
containing them. 
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SEE ALSO 

ppmtogif(l), ppm(5) 

AUTHOR 

Copyright © 1993 by D avid Koblas(kobias@netcom.com) 

29 September 1993 


gindxbib 

gindxbib— M ake inverted index for bibliographic databases 

SYNOPSIS 

gindxbib [ -vw] [-c file] [-d dir] [-f file] [-h n] [—i s t r i ng ] 
[-k n] [-1 n] [-n n] [-0 file] [-t n] [filename ...] 


DESCRIPTION 

gindxbib makes an inverted index for the bibliographic databases inti i e n a me ... for use with grefer(l), giookbib(l), and 
lkbib(l). The index will be named f i i ename .i; the index is written to a temporary file which is then renamed to this. If no 
filenames are given on the command line because the-t option has been used, and no -o option is given, the index will be 
named ind.i. 

Bibliographic databases are divided into records by blank lines. W ithin a record, each fields starts with a % character at the 
beginning of aline. Fields have a one-letter name that follows the % character. 

The values set by the -c, -n, - 1 , and -t options are stored in the index; when the index is searched, keys will be discarded and 
truncated in a manner appropriate to these options; the original keys will be used for verifying that any record found using 
the index actually contains the keys. This means that a user of an index need not know whether these options were used in 
the creation of the index, provided that not all the keys to be searched for would have been discarded during indexing and 
that the user supplies at least the part of each key that would have remained after being truncated during indexing. The value 
set by the-i option is also stored in the index and will be used in verifying records found using the index. 


OPTIONS 

-v Print the version number. 

-w Index whole files. Each file isa separate record. 

-cf i 1 e Read the list of common words from f i i e instead of /usr/iib/groff/eign. 

-ddi r U se d i r as the pathname of the current working directory to store in the index, instead of the path printed 

by pwd(l). Usually di r will be a symbolic link that points to the directory printed by pwd(l). 

-tf i 1 e Read the files to be indexed from file. If file is-, files will be read from the standard input. The-f option 

can be given at most once 

-is t r i ng Don't index the contents of fields whose names are in s t r i ng . Initially, stri ng isxyz. 

- 1 ™ Use the first prime greater than or equal ton for the size of the hash table Larger values of n will usually 

make searching faster, but will make the index larger and gindxbib use more memory. Initially, n is 997 . 

-kn Use at most n keys per input record. Initially, n is 100. 

-in Discard keys that are shorter than n. Initially, n is 3. 

-nn Discard then most common words. Initially, n islOO. 

-obasename T he index Should benamedbasename.i. 

-tn Truncate keys ton. Initially, n is 6. 



Parti: User Commands 

FILES 

f i I e n a me . i 

Ind.i 

/usr/lib/groff/eign 
indxbibXXXXXX 

SEE ALSO 

grefer(l), lkbib(l), glookbib(l) 


Index 

Default index name 
List of common words 
T emporary file 
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glookbib 

giookbib— Search bibliographic databases 

SYNOPSIS 

glookbib [ -v ] [-is t r i n g ][-tn ] filename ... 

DESCRIPTION 

giookbib prints a prompt on the standard error (unless the standard input is not a terminal), reads from the standard input a 
line containing a set of keywords, searches the bibliographic databasesf i i ena me ... for references containing those keywords, 
prints any references found on the standard output, and repeats this process until the end of input. For each database 
f i i e n a me to be searched, if an index fi i ename .i created by gindxbib(l) exists, then it will be searched instead; each index can 
cover multiple databases. 

OPTIONS 

-v Print the version number. 

- 1 st ring When searching files for which no index exists, ignore the contents of fields whose names are in stri ng. 

-tn Only require thefirstn characters of keys to begiven. Initially, n is 6. 

FILE 

filename.i I ndex files 

SEE ALSO 

grefer(l), lkbib(l), gindxbib(l) 

gnroff 

gnroff— Emulate nroff Command with groff 

SYNOPSIS 

gnroff [ -h ] [—i ] [-mna me ] [-nn u m ] [-ol i s t ] [ - rc n ] [-T n a me ] [f i I e. , , ] 

DESCRIPTION 

The gnroff script emulates the nroff command using groff. The -t option with an argument other than ascii and latim 
will beignored. The-h option is equivalent to thegrotty -h option. The-i, -n, -m, -o, and -r options have the effect 
described in gtroff(l). In addition, gnroff silently ignores options of -e, -q, or -s. 
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SEE ALSO 

groff(l), gtroff(l), grotty(l) 
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gouldtoppm 

gouidtoppm— C onvert Gould scanner file into a portable pixmap 

SYNOPSIS 

gouldtoppm[goul dfiI e ] 

DESCRIPTION 

Reads a file produced by the Gould scanner as input. Produces a portable pixmap as output. 

SEE ALSO 

ppm(5) 

AUTHOR 

Copyright© 1990 by Stephen Paul Lesniewski 

20 May 1990 
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gpic— Compile pictures for trotf orTeX 

SYNOPSIS 

gpic [ -nvC ] [filename ... ] gpic -t [ -cvzC ] [filename ... ] 

DESCRIPTION 

This manual page describes the GN U version of pic, which is part of the groff document formatting system, pic compiles 
descriptions of pictures embedded within troft orTeX input files into commands that are understood byTeX or troff. 

Each picture starts with a line beginning with .ps and ends with aline beginning with .pe. Anything outside of .ps and .pe 
is passed through without change. 

It is the user's responsibility to provide appropriate definitions of theps and pe macros. W hen the macro package being used 
does not supply such definitions (for example, old versions of -ms), appropriate definitions can be obtained with -mpic: These 
will center each picture. 

OPTIONS 

Options that do not take arguments may be grouped behind a single-. The special option — can be used to mark the end of 
the options. A filename of - refers to the standard input. 

-c Recognize .ps and .pe a/en when followed by a character other than space or newline. 

-n Don't use the groff extensions to the troff drawing commands. You should use this if you are using a 

postprocessor that doesn't support these extensions. The extensions are described in groffj>ut(5). The-n option 
also causes pic not to use zero-length lines to draw dots in troff mode. 

-t TeX mode. 

-c Be more compatible with tpic. Implies-t. Lines beginning with n are not passed through transparently. Lines 
beginning with . are passed through with the initial . changed to\.A line beginning with .ps is given special 
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treatment: It takes an optional integer argument specifying the line thickness (pen size) in milli-inches; a missing 
argument restores the previous line thickness; the default line thickness is 8 milli-inches. The line thickness thus 
specified takes effect only when a nonnegative line thickness has not been specified by use of thethickness 
attribute or by setting the linethick variable 
-v Print the version number. 

-z InTeX mode draw dots using zero-length lines. 

Thefollowing options supported by other versionsof pic areignored: 

-d Draw all linesusingthe\Descapesequence. pic always does this. 

-Tdev G enerate output for thetroff device dev. This is unnecessary because the troff output generated by pic is device¬ 
independent. 



USAGE 

This section describes only the differences between GNU pic and the original version of pic. M any of these differences also 
apply to newer versionsof UNIX pic. 


mode is enabled by the -t option. In mode, pic will define a vbox called ngraph for each picture. You must yourself print that 
vbox using, for example, the command: 

\centerline{\box\graph} 

Actually, since the vbox has a height of zero, this will produce slightly more vertical space above the picture than below it, the 
line 

\centerline{\raise 1em\box\graph} 
would avoid this. 

You must use a driver that supports the tpic specials, version 2. 

Lines beginning with \are passed through transparently; a % is added to the end of thelineto avoid unwanted spaces. You 
can safely use this feature to change fonts or to change the value of \baseiineskip. Anything else may well produce undesir¬ 
able results; use at your own risk. Lines beginning with a period are not given any special treatment. 


COMMANDS 

for variable = expr 1 to expr2 
by [*]expr3] do X body X 
[Set variable to expr 1 

if expr then X if-1 r ue X 
[else Y if-false Y] 
print arg ... 

command arg ... 


sh X command X 
copy "f i I ename" 

copy ["filename"] thru X body X 
[until "word"] 

copy ["filename"] thru macro 
[until "word"] 


W hile the value of vari abi e is less than or equal to expr 2 , do body and increment 
variable by expr 3; if by is not given, increment var i able by 1 . If expr 3 is prefixed 
by * then variable will instead be multiplied by expr 3. x can be any character not 
occurring in body. 

Evaluate expr; if it is nonzero,do i f-t rue; otherwise, do.lf-f ai se. u can beany 
character not occurri ng in i f - 1 r ue. y can be any character not occurring in i f - f a i s e. 
Concatenate the arguments and print as a line on stderr. Each arg must bean 
expression, a position, or text. This is useful for debugging. 

Concatenate the arguments and pass them through as a line to troff orTeX. Each 
arg must bean expression, a position, or text. This has a similar effect to aline 
beginningwith . or \, but allows thevalues of variables to be passed through. 

Pass command to a shell, x can beany character not occurring in command. 

Included i ename at this point in the file. 

T his construct does body once for each line of f i i ename; thelineissplit into blank- 
delimited words, and occurrences of $ i in body, fori between 1 and 9, are replaced 
by the i -th word of the line If f i i ename is not given, lines are taken from the current 
input up to .pe. If an until clause is specified, lines will be read only until a line the 
first word of which is wor d ; that line wilI then be discarded, x can beany character 
not occurring in body. For example, 
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.PS 

copy thru % circle at ($1,$2) % until "END" 
1 2 
3 4 
5 6 
END 
box 
.PE 

is equivalent to 

.PS 

circle at (1,2) 
circle at (3,4) 
circle at (5,6) 
box 
.PE 


reset vari abl el, vari abI e2 


plot expr ["text"] 


v a r i a b I e: =e x p r 


Arguments of the form 
XanythingX 

are also all owed to be of the form: 

anything 

In this case, anything can contain balanced occurrences of and .br. Strings may contain x or imbalanced occurrences of 

and .BR. 

EXPRESSIONS 

The syntax for expressions has been significantly extended: 

x A y (exponentiation) 

sin(x) 

cos(x) 

atan2(y,x) 

log(x) (base 10) 

exp(x) (base 10, ie 10'-.4m'x 1 .4m') 
sqrt(x) 
int(x) 

rand() (return a random number between 0 and 1) 
rand(x) (return a random number between 1 and x; deprecated) 
max (el ,e2) 
min(el ,e2) 

!e 


The commands to be performed for each line can also betaken from a macro 
defined earl ier by giving the name of the macro as the argument to thru. 

Reset predefined variables mi abl ei, va r i a bi e 2 ... to their default values. If no 
arguments are given, reset all predefined variables to their default values. Note that 
assigning a value to scale also causes all predefined variables that control dimensions 
to be reset to their default values times the new value of scale. 

T his is a text object which is constructed by using as a format string for t ext sprintf 
with an argument of expr . If text is omitted, a format string of %g is used. Attributes 
can be specified in thesameway as for a normal text object. Bevery careful that you 
specify an appropriate format string; pic does only very limited checking of the 
string. This is deprecated in favor of sprintf. 

This is similar to = except v a r i abl e must already be defined, and thevalueof 
variable will be changed only in the innermost block in which it is defined. (By 
contrast, = defines the variable in the current block if it is not already defined there, 
and then changes the value in the current block.) 
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el && e2 
el || e2 
el == e2 
el != e2 
el >= e2 
el > e2 
el <= e2 
el < e2 
"strl "== ll str2 11 
"strl"!="str2" 

String comparison expressions must be parenthesized in so me con texts to avoid ambiguity. 

OTHERCHANGES 

A bare expression, expr, is acceptable as an attribute; it is equivalent to di r expr, where di r is the current direction. For 

example 

line 2i 

means draw a line 2 inches long in the current direction. 

The maximum width and height of the picture are taken from the variables maxpswid and maxpsht. Initially, these have values 
8.5 and 11. 

Scientific notation is allowed for numbers. For example 

x = 5e-2 

Text attributes can be compounded. For example 
"too" above ljust 

is legal. 

There is no limit to the depth to which blocks can be examined. For example 

[A: [B: [C: box ]]] with .A.B.C.sw at 1,2 
circle at last [].A.B.C 

is acceptable. 

Arcsnow have compass points determined by thecircleof which the arc isa part. 

Circles and arcs can be dotted or dashed. In mode, splines can be dotted or dashed. 

Boxes can have rounded corners. T he rad attribute specifies the radius of the quarter-circles at each corner. If no rad or diam 
attribute is given, a radius of boxrad is used. Initially, boxrad has a value of 0 . A box with rounded corners can be dotted or 
dashed. 

The .ps line can have a second argument specifying a maximum height for the picture. If the width of zero is specified, the 
width will be ignored in computing the scaling factor for the picture. N otethat GN U pic will always scale a picture by the 
same amount vertically as horizontally. This is different from theD WB 2.0 pic, which may scale a picture by a different 
amount vertically than horizontally if a height is specified. 

Each text object has an invisible box associated with it. T he compass points of a text object are determined by this box. T he 
implicit motion associated with the object is also determined by this box. The dimensions of this box are taken from the 
width and height attributes; if thewidth attribute is not supplied, then thewidth will betaken to be textwid; if the height 
attribute is not supplied, then the height will betaken to be the number of text strings associated with the object times 
textht. Initially textwid and textht havea value of 0 . 

In places where a quoted text string can beused, an expression oftheform: 
sprintf (f or mat ,a rg ,... ) 
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can also be used; this will produce the arguments formatted according to for mat, which should beastring as described in 
printf (3), appropriate for the number of arguments supplied, using only thee, t, g, or% format characters. 

The thickness of the lines used to draw objects iscontrolled by theiinethick variable. This gives the thickness of lines in 
points. A negative value means use the default thickness: in outputmode, this means use a thickness of 8 milli-inches; in 
output mode with the -c option, thismeansusetheline thickness specified by .ps lines; in troff output mode, thismeans 
use a thickness proportional to the point size. A zero value means draw the thinnest possible line supported by the output 
device. Initially, ithasavalue of - 1 . T here isalso a thickfness] attribute. For example, 
circle thickness 1.5 

would draw a circle using a line with a thickness of 1.5 points. The thickness of lines is not affected by the value of the scale 
variable, nor by the width or height given in the .ps line. 

Boxes (including boxes with rounded corners), circles, and ellipses can be filled by giving then an attribute of fiii[ed] . This 
takes an optional argument of an expression with a value between 0 and 1 ; 0 will fill it with white, 1 with black, values in 
between with a proportionally gray shade. A value greater than 1 can also be used: this means fill with the shade of gray that 
is currently being used for text and lines. N ormally this will be black, but output da/ices may provide a mechanism for 
changing this. W ithoutan argument, then the value of the variable f nival will be used. Initially, this has a value of 0 . 5 . The 
invisible attribute does not affect the filling of objects. Any text associated with a filled object will be added after the object 
has been filled, so that the text will not be obscured by the filling. 

Arrowheads will be drawn as solid triangles if the variable arrowhead is nonzero and either mode is enabled or the -x option 
has been given. Initially, arrowhead has a value of 1 . 

The troff output of pic is device-independent. The -t option is therefore redundant. All numbers are taken to be in inches; 
numbers are never interpreted to be in troff machine units. 

Objects can have an aligned attribute. This will only work when the postprocessor isgrops. Any text associated with an 
object having the aligned attribute will be rotated about the center of the object so that it is aligned in the direction from the 
start point to the end point of the object. N ote that this attribute will have no effect for objects whose start and end points 
are coincident. 

In places where nth is allowed, expr 'th isalso allowed. N ote that th is a single token: no space is allowed between the 1 and 
the th. For example, 

fori =1 to 4 do{ 

line from 1 i 1 th box.nw to 1 i+1 1 th box.se 
} 

FILE 

/usr/iib/groff/tmac/tmac.pic Sample defi nitions of the PS and PE macros. 

SEE ALSO 

gtroff(l), groff_out(5), tex(l) 

TPIC: PIC for AT&T Bell Laboratories, Computing Science Technical ReportNo. 116, PIC— A GraphicsLanguagefor 
Typesetting. (This can be obtained by sending an e-mail message to netiib@research.att.com with a body of "send 116 from 
research/cstr.") 

BUGS 

Input characters that are illegal for groff (those with ASCII codeO or between 013 and 037 octal or between 0200 and 0237 
octal) arerejected even in mode. 

The interpretation of f nival is incompatible with the pic in 10th edition U NIX, which interprets 0 as black and 1 as white. 
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gprof 

gprot— Display call graph profile data 

SYNOPSIS 

gprof [ -abcsz ] [ -ej-E name ] [-fj -F name ][-k fromname toname ] [ objfile [ gmon.out ]] 

DESCRIPTION 

gprot produces an execution profile of C, Pascal, or Fortran77 programs. The effect of called routines is incorporated in the 
profileof each caller. The profile data i s taken from thecall graph profile file (gmon.out default), which iscreated by programs 
that are compiled with the -pg option of cc(l), pc(l),and f77(l). The-pg option also links in versions of the library routines 
that are compiled for profiling, gprof reads thegiven object fi le (the default is a. out) and establishes the relation between its 
symbol table and thecall graph profile from gmon.out. If more than one profile file is specified, the gprof output shows the 
sum of the profile information in thegiven profile files. 

gprof calculates the amount of time spent in each routine. N ext, these times are propagated along the edges of thecall graph. 
Cycles are discovered, and cal Is into a cycle are made to share the time of the cycle. The first listing shows thefunctions 
sorted according to the time they represent, including the time of their call graph descendants. Below each function entry is 
shown its (direct) call graph children, and how their times are propagated to this function. A similar display above the 
function shows how thisfunction'stimeand thetimeof its descendants is propagated to its(direct) call graph parents. 

Cycles are also shown, with an entry for the cycle as a whole and a listing of the members of the cycle and their contributions 
to thetimeand call counts of the cycle. 

Second, aflat profile is given, similar to that provided by prof (1). This listing gives the total execution times, thecall counts, 
the time in milliseconds, thecall spent in the routine itself, and the time in mi Hi seconds the call spent in the routine itself, 
including its descendants 

Finally, an index of the function names is provided. 

OPTIONS 

The following options are available: 

-a Suppresses the printing of statically declared functions. If thisoption isgiven, all relevant information 

about the static function (for example, time samples, calls to other functions calls from other 
functions) belongs to thefunction loaded just beforethe static function in the objfile file. 

-b Suppresses the printing of a description of each field in the profile. 

-c The static call graph of the program is discovered by a heuristic that examines the text space of the 

object file. Static-only parents or children are shown with call counts of 0 . 

-e name Suppresses the printing of the graph profile entry for routine n a me and all its descendants (unless they 

have other ancestors that aren't suppressed). M ore than one-e option may be given. Only one name 
may be given with each -e option. 

-e name Suppresses the printi ng of the graph profile entry for routine name (and its descendants) as-e, 

previously and also excludes the time spent in name (and its descendants) from the total and percentage 
time computations. (For example, -e mcount -e mcieanup is the default.) 

-f name Prints the graph profile entry of only the specified routine na me and its descendants. M orethan one-f 

option may be given. Only onename may be given with each -f option. 

-f name Prints the graph profile entry of only the routi ne na me and its descendants (as-f, previously) and also 

uses only the times of the printed routinesin total timeand percentage computations. M orethan one 
-f option may be given. Only onename may be given with each -f option. The -f option overrides the 
-e option. 

-k fromname toname Will delete any arcs from routi ne f romna me to routi ne t oname . This can be used to break undesired 

cycles. M orethan one-k option may be given. Only one pair of routine names may be given with each 
-k option. 
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-s A prof ilefilegmon. sum is produced that represents the sum of the profile information in all the specified 

profile files. This summary profile file may be given to later executions of gprof (probably also with an 
-s) to accumulate profile data across several runsof an objfiie file. 

-v Prints theversion number for gprof, and then exits. 

-z D isplays routines that have zero usage(as shown by call counts and accumulated time). Thisisuseful 

with the-c option for discovering which routines were never called. 

FILES 

a.out The name list and text space 

gmon.out Dynamic call graph and profile 

gmon.sum Summarized dynamic call graph and profile 

SEE ALSO 

monitor(3), profil(2), cc(l), prof(l) 

"An Execution Profiler for M odular Programs," by S. Graham, P. Kessler, M . M cKusick; Software- Practiceand Experience, 

Vol. 13, pp. 671-685, 1983. 

"gprof: A Call Graph Execution Profiler," by S. Graham, P. Kessler, M . M cKusick; ProceedingsoftheSIGPLAN '82 
Symposium on Compiler Construction, SI G PLAN Notices, Vol. 17, N o 6, pp. 120-126, June 1982. 

HISTORY 

gprof appeared in 4.2 BSD. 

BUGS 

The granularity of the sampling is shown, but remains statistical at best. We assume that the time for each execution of a 
function can be expressed by the total time for the function divided by the number of times the function is called. Thus, the 
time propagated along the call graph arcs to the function's parents is directly proportional to the number of times that arc is 
traversed. 

Parents that are not them selves profiled will have the time of their profiled children propagated to them, but they will appear 
to be spontaneously invoked in thecall graph listing, and will not have their time propagated further. Similarly, signal 
catchers, even though profiled, will appear to be spontaneous (although for more obscure reasons). Any profiled children of 
signal catchers should have thei r times propagated properly, unless thesignal catcher was invoked duringtheexecution of the 
profiling routine in which case all Is lost. 

The profiled program must call exit(2) or return normally for the profiling information to be saved in the gmon.out file. 

29 January 1993 
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grefer— Preprocess bibliographic references for groff 

SYNOPSIS 

grefer [ - benvCPRS] [-a n] [-c fields] [-f n] [-i fields] [-k field] [-1 m, n ] [-p filename] [-s fields] [-t n] [-B 
field.macro] [filename...] 

DESCRIPTION 

This file documents the GN U version of refer, which is part of the groff document formatting system, refer copies the 
contents of f i i e name ... to the standard output, except that lines between .[and . ] are interpreted as citations and lines 
between .ri and .R2 are interpreted as commands about how citations are to be processed. 
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Each citation specifies a reference. The citation can specify a reference that is contained in a bibliographic database by giving 
a set of keywords that only that reference contains. Alternatively, it can specify a reference by supplying a database record in 
thecitation. A combination of these alternatives is also possible. 

For each citation, refer can produce a mark in the text. This mark consists of some label that can be separated from the text 
and from other labels in various ways. For each reference, it also outputs groff commands that can be used by a macro 
package to produce a formatted reference for each citation. The output of refer must therefore be processed using a suitable 
macro package. The -ms and -me macros are both suitable. The commands to format a citation's reference can be output 
immediately after the citation, or the references may be accumulated, and the commands output at some later point. If the 
references are accumulated, then multiple citations of the same reference will produce a single formatted reference 

The interpretation of lines between .ri and .R 2 ascommandsisa new feature of GN U refer. Documents making use of this 
feature can still be processed by U NIX refer just by adding the lines: 

.de R1 
■ ig R2 


to the beginning of the document. This will cause troff to ignore everything between .ri and ,R 2 . The effect of 9ome 
commands can also be achieved by options. These options are supported mainly for compatibility with UNIX refer. It is 
usually more convenient to use commands. 

refer generates .if lines so that filenames and line numbers in messages produced by commands that read refer output will 
be correct; it also interprets lines beginning with .if so that filenames and line numbers in the messages and .if lines that it 
produces will be accurate even if the input has been preprocessed by a command such asgsoeiim(l). 

OPTIONS 

M ost options are equivalent to commands (for a description of these commands, see "Commands," later in this manual 


page): 


-b 

no-label-in-text; no-label-in-reference 

-e 

accumulate 

-n 

no-default-database 

-C 

compatible 

-P 

move-punctuation 

-S 

label "(A.njQ) ' (D.yjD)"; bracket-label 

-an 

reverse An 

-cf i el ds 

capitalize fields 

-fn 

label %n 

-if i el ds 

search-ignore fields 

-k 

label L%a 

-kf i el d 

label field %a 

-1 

label A.nD.y%a 

-lm 

label A.n+mD.y%a 

—1, n 

label A.nD.y-n%a 

-lm,n 

label A.n+mD.y-n%a 

-pf i 1 ename 

database fi 1 ename 

-ss pec 

sort spec 

-tn 

search-truncate n 


These options are equivalent to the foil owing commands with the addition that the filenames specified on the command line 
are processed as if they were arguments to the bibliography command instead of in the normal way: 


-B 

-Bf i el d.macr o 


Annotate X AP; no-label-in-reference 
Annotate field macro; no-label-in-reference 
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T hefollowing options have no equivalent commands: 

-v Print the version number 

-r Don't recognize lines beginning with .ri/.r 2 

USAGE 

BIBLIOGRAPHIC DATABASES 

The bibliographic database is a text file consisting of records separated by one or more blank lines. W ithin each record, fields 
start with a% at the beginning of a line. Each field has a one-character name that immediately follows the%. It is best to use 
only uppercase and lowercase letters for the names of fields. The name of the field should be followed by exactly one space, 
and then by the contents of thefield. Empty fields are ignored. The conventional meaning of each field isas follows: 

a The name of an author. If the name contains a title such as Jr. at the end, it should be separated from the 

last name by a comma. There can be multiple occurrences of the a field. The order is significant. It is a 
good idea always to supply an a field or a q field. 
b Foran articlethat is part of a book, the title of the book, 

c The place (city) of publication. 

d Thedateof publication. Theyear should be specified in full. If the month is specified, thename rather 

than the number of the month should be used, but only the first three letters are required. It is a good idea 
always to supply a d field; if the date is unknown, a value such as in press or unknown can be used. 
e Foran articlethat is part of a book, the name of an editor of the book. W here the work has editors and no 

authors the names of the editors should be given as a fields (ed) or (eds) should be appended to the last 
author. 

g U .S. government ordering number, 

i The publisher (issuer), 

j Foran article in ajournal, the name of the journal. 

k Keywords to be used for searching. 

l Label. 

n Journal issue number. 

o Other information. This is usually printed at the end of the reference, 

p Page number. A range of pages can be specified asm-n. 

q The name of the author, if the author is not a person. This will only be used if there are no a fields. There 

can only beoneo field. 
r Technical report number, 

s Series name. 

t Title. Foran article in a book or journal, thisshould be the title of the article, 

v Volume number of the journal or book, 

x Annotation. 

For all fields except a and e, if there is more than one occurrence of a particular field in a record, only the last such field will 
be used. 

If accent strings are used, they should follow the character to be accented. This means that the am macro must be used with 
the -ms macros. Accent stri ngs should not be quoted: use one \ rather than two. 

CITATIONS 

The format of a citation is 

.[openi ng-1 ext 
flags keywords 
fields 

.]cI os i ng-1 ext 
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Theopeni ng-text, cl osi ng-text, and f i ags components are optional. Only one of the key words and fields components need 
be specified. 

The keywords component says to search the bibliographic databases for a reference that contains all the words in keywords. It 
is an error if more than one reference if found. 

T he f i ei ds components specifies additional fields to replace or supplement those specified in the reference. When references 
are being accumulated and thekey words component is nonempty, then additional fields should be specified only on the first 
occasion that a particular reference is cited, and will apply to all citations of that reference. 

Theopeni ng-text and cl osi ng-text component specifies strings to beused to bracket the label instead of the strings specified 
in the bracket-label command. If either of these components is nonempty, the strings specified in the bracket-label 
command will not beused; this behavior can be altered using the [ and ] flags. N otethat leading and trailing spaces are 
significant for these components 

Then ags component is a list of nonalphanumeric characters, each of which modifies the treatment of this particular 
citation. UNIX refer will treat these flags as part of the keywords and so will ignore them because they are 
nonalphanumeric. Thefollowing flags are currently recognized: 

# This says to use the label specified by the short-label command, instead of that specified by the label command. 

If no short label has been specified, the normal label will beused. Typically, the short label is used with author- 
date labelsand consists of only thedate and possibly a disambiguating letter; the# issupposedto be suggestive of 
a numeric type of label. 

[ Precede openi ng-text with the first string specified in thebracket-iabei command. 

I Follow ci osi ng-text with the second string specified in the bracket-label command. 

One advantage of using the [ and ] flags rather than including the brackets in openi ng-text and ci osi ng-text is that you can 
change the style of bracket used in the document just by changing the bracket-label command. Another advantage is that 
sorting and merging of citations will not necessarily be inhibited if the flags are used. 

If a label is to be inserted into the text, it will be attached to the line preceding the.[ line. If there is no such line then an 
extra linewill be inserted before the. [ lineand awarningwill be given. 

There is no special notation for making a citation to multiple references. J ust use a sequence of citations, one for each 
reference. Don't put anything between the citations. The labels for all the citations will be attached to the line preceding the 
first citation. The labels may also be sorted or merged. (See the description of the <> label expression, and of thesort- 
adjacent- labels and abbreviate-label-ranges Command.) A label Will not be merged if its citation hasa nonempty openi ng- 
text orci osi ng-text . H owever, the labels for a citation using the] flag and without any ci osi ng-text immediately followed 
by a citation using the [ flag and without any openi ng-text may be sorted and merged a/en though the first citation's 
openi ng-text or the second citation'sei osi ng-text is nonempty. (If you want to prevent this, just make the first citation's 

closing-text \ &.) 

COMMANDS 

Commands are contained between lines starting with .ri and ,R2. Recognition of these lines can be prevented bythe-R 
option. When an .ri line is recognized, any accumulated references are flushed out. N either .ri nor ,R2 lines, nor anything 
between them, is output. 

Commands are separated by newlines or semicolons. # introduces a comment that extends to the end of the line (but does 
not conceal the newline). Each command is broken up into words. Words are separated by spaces or tabs. A word that begins 
with an open quote (") extends to the next close quote (") that is not followed by another open quote ("). If there is no such 
open quote(") theword extends to theend of theline. Pairs of open quotes)") in aword beginningwith collapse to a single 
open quote("). Neither#nor; is recognized inside open quotes ("). A linecan be continued by ending it with \;thisworks 
everywhere except after a #. 

Each command name that is marked with * has an associated negative command no-name that undoes the effect of name. For 
example, the no-sort command specifies that references should not be sorted. The negative commands take no arguments. 
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In the following description, each argument must be a single word; field is used for a single uppercase or lowercase letter 
naming afield; fields is used for a sequence of such letters; m and n are used for a nonnegative numbers; string is used for an 
arbitrary string; fi i ena me is used for the name of a file. 

abbreviate*f i el ds stringi Abbreviate the first names of f i ei ds . An initial letter will be separated from another 

stri ng 2 string3st r i ng4 initial letter by st r i ng i , from the last name by s t r i ng2 , and from anything else (such 

as a von or de) by stri ng3. These default to a period followed by a space. In a 
hyphenated first name, the initial of the first part of the name will be separated from 
the hyphen by stri ng4 ; this defaults to a period. N o attempt is made to handle any 
ambiguities that might result from abbreviation. N ames are abbreviated before 
sorting and beforelabel construction. 

abbreviate-iabei-ranges*st ring T hree or more adjacent labels that refer to consecutive references will beabbreviated 

to a label consisting of the first label, followed by stri ng, followed by the last label. 
This is mainly useful with numeric labels. If stri ng is omitted it defaults to -. 
accumulate* Accumulate references instead of writing out each reference as it is encountered. 

Accumulated references will be written out whenever a reference of the form: 

■ [ 

$LIST$ 

■] 


annotate*f i el dstring 


articlesst ring ... 
string ... 

bibliographyf i I e n a me 
bracket-labelstri ng 
1string2st r i ng3 


capitalizefiel ds 
compatible* 

databasef i I ename... 


date-as-label*st ring 


default-database* 


is encountered, after all input files have been processed, and whenever an .ri line is 
recognized. 

field is an annotation; print it at the end of the reference as a paragraph preceded by 

the line 

.string 

If macro is omitted, it will default to Ap;if field is also omitted, it will default to x. 
Onlyonetieid can bean annotation. 

These are definiteor indefinite articles, and should beignored at the begi nning of t 
fields when sorting. Initially, the, a, and an are recognized as articles. 

Write out all the references contained in the bibliographic databases f i i ename ... 

In the text, bracket each label with stringi and stri n g 2 . An occurrence of stri ng 2 
immediately followed by stri ngi will be turned into stri ng 3 . The default behavior is 
bracket-label \*([. \*(.]"," 

Convertfi ei ds to caps and small caps. 

Recognize .ri and .R 2 a/en when followed by a character other than space or 
newline 

Search the bibliographic databases fi 1 ename ... For each f i 1 ename if an index 
fi 1 ename .i created by gindxbib(l) exists, then it will be searched instead; each index 
can cover multi pie databases. 

string is a label expression that specifies a string with which to replacethe d field 
after constructing the label. See "Label Expressions," later in this manual page, fora 
description of label expressions. This command is useful if you do not want explicit 
labels in the reference list, but instead want to handle any necessary disambiguation 
by qualifying the date in someway. The label used in the text would typically be 
some combination of the author and date. In most cases, you should also usetheno- 
iabei-in-reference command. For example, 
date-as-label D.+yD.y%a*D.-y 

would attach a disambiguating letter to the year part of the d field in the reference. 
The default database should be searched. This is the default behavior, so the negative 
version of thiscommand ismore useful, refer determines whether the default 
database should be searched on the first occasion that it needs to do a search. Thus, a 
no-defauit-database command must be given before then, in order to be effective. 



Parti: User Commands 


discard*fi elds 
et-al*st r i ng mn 


includef i I ename 
join-authorsst ri ngl 
string2st ri ng 3 


label-in-reference* 

label-in-text* 


labels t ring 

separate-label-second-parts 
st ri ng 

move-punctuation* 


reverse*st ri ng 


search-ignore*f i el ds 
search-truncate*n 


short-label*st r i ng 


sort*st ri ng 


sort-adj acent-labels* 


When the reference is read.fi elds should be discarded; no string definitions for 
fi ei ds will be output. Initially, fi ei ds arexyz. 

Control use of et al in the evaluation of @ expressions in label expressions If the 
number of authors needed to make the author sequence unambi guous is u and the 
total number of authors ist, then the last t - u authors will be replaced by s t r i ng, 
provided that t - u is not less than m and t is not less than n . T he default behavior is 

et-al " et al" 2 3. 

Included i ena me and interpret the contents as commands. 

This says how authors should be joined together. When there are exactly two 

authors they will bejoined with stiff ngi. When there are more than two authors, all 

but the last two will bejoined with stri ng 2 , and the last two authors will bejoined 

with stri ng3. Ifstri ng3 is Omitted, it Will default to s t r i ngl; ifstri ng2 isalSO 

omitted, itwill also default to stri ng 1 . For example, 

join-authors " and 11 ", 11 ", and 11 

will restore the default method for joining authors. 

When outputting the reference define the string [f to be the reference's label. This 
is the default behavior; so the negative version of this command is more useful. 

For each reference, output a label in the text. The label will be separated from the 
surrounding text as described in the bracket-label command. This isthe default 
behavior; so the negative version of thiscommand ismore useful, 
string is a label expression describing howto label each reference. 

When merging two-part labels, separate the second part of the second label from the 
first label with stri ng . See the description of the <> label expression. 

In the text, move any punctuation at the end of line past the label. It is usually a 
good idea to give this command unless you are using superscripted numbers as 
labels. 

Reverse the fields whose names are in st ri ng. Each field name can be followed by a 
number that says how many such fields should be reversed. If no number is given for 
afield, all such fields will be reversed. 

While searching for keys i n databases for which no index exists, ignore the contents 
off i ei ds. Initially, fields xyz areignored. 

Only require thefirstn characters of keys to be given. In effect, when searching fora 
given key, wordsin the database are truncated to the maximum of n and the length 
of the key. Initially, n is 6 . 

string is a label expression that specifies an alternative (usually shorter) style of label. 
This is used when the# flag is given in the citation. When using author-date style 
labels, the identity of the author or authors issometimes clear from the context, and 
so it may be desirable to omit the author or authors from the label. T he short - label 
command will typically be used to specify a label containing just a date and possibly 
a disambiguating letter. 

Sort references according to string. References will automatically be accumulated, 
stri ng should be a list of field names, each followed by anumber, indicating how 
many fields with the name should be used for sorting. + can be used to indicate that 
all the fields with the name should beused. Also, . can beused to indicate the 
references should be sorted using the (tentative) label. (The "Label Expressions” 
subsection describes the concept of a tentative label.) 

Sort labels that are adjacent in the text according to their position in the reference 
list. Thiscommand Should usually be given if the abbreviate-label-ranges 
command has been given, or ifthe label expression containsa<> expression. This 
will have no effect unless references are being accumulated. 
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LABEL EXPRESSIONS 


Label expressions can be evaluated both normally and tentatively. The result of normal evaluation is used for output. The 
result of tentative evaluation, called the tentative label, is used to gather the information that normal evaluation needs to 
disambiguate the label. Label expressions specified by the date-as-label and short -iabei commands are not evaluated 
tentatively. N ormal and tentative evaluation are the same for all types of expression other than @, *, and % expressions. The 
following description applies to normal evaluation, except where otherwise specified. 


field, field n 
'string' 


%n, %a, %A, %i, %I 


expr * 

expr +n, expr-n 

expr .1 
expr .u 
expr .c 
expr .r 
expr .a 


expr .y 
expr .+y 
expr .-y 
expr .n 
exprlexpr 2 
expr1 expr 2 
expr1|expr 2 
e x p r 1 &e x p r 2 
exprl?expr2 :expr 3 
<e x p r > 


Thenth part of field. If n is omitted, it defaults to i. 

T he characters in st ri ng literally. 

All the authors joined as specified by the join-authors command. The whole of each author'sname 
will be used. H owever, if the references are sorted by author (that isthe sort specification starts with 
A+),then authors' last names will beused instead, provided that thisdoes not introduce ambiguity, and 
also an initial subsequence of the authors may beused instead of all theauthors, again provided that 
thisdoes not introduce ambiguity. The use of only the last name for the i -th author of some reference 
is considered to be ambiguous if there is some other reference, such that the first i - i authors of the 
references are the same, the i-th authors are not the same, but the i-th authors' last names are the 
same. A proper initial subsequence of the sequence of authors for some reference isconsidered to be 
ambiguous if there is a reference with some other sequence of authors that also has that subsequence as 
a proper initial subsequence. When an initial subsequence of authors is used, the remaining authors are 
replaced by the string specified bytheet-ai command; thiscommand may also specify additional 
requirements that must be met before an initial subsequence can beused. @ tentatively evaluates to a 
canonical representation of theauthors, such that authors that compare equally for sorting purpose will 
h ave th e sam e rep resen tati on. 

The serial number of the reference formatted according to the character following the %. The serial 
number of a reference is i pi us the number of earlier references with same tentative label as this 
reference. T hese expressions tentatively evaluate to an empty string. 

If there is another reference with the same tentative label as this reference, then expr; otherwise, an 
empty string. It tentatively evaluatesto an empty string. 

The first (+) or last (-) n uppercase or lowercase letters or digits of expr. troff special characters (such 

as \ < 1 a) count as a single letter. Accent strings are retained but do not count toward the total. 

expr converted to lowercase. 

expr converted to uppercase. 

expr converted to caps and small caps. 

expr reversed so that the last name is first. 

expr with first names abbreviated. Note that fields specified in theabbreviate command are abbrevi¬ 
ated before any labels are evaluated. Thus .a is useful only when you want afield to be abbreviated in a 
label but not in a reference. 

Theyear part of expr. 

The part of expr before the year, orthewholeof expr if it does not contain ayear. 

The part of expr after the year, or an empty string if expr does not contain ayear. 

The last name part of expr. 

expr l except that if the last character of expr i is-then itwill be replaced by e x p r 2. 

The concatenation ofexpri and expr 2. 

If expr 1 is nonempty, then expr 1; otherwise, expr 2. 

If expri is nonempty, then ex pr 2 ; otherwise, an empty string. 

If expr 1 is nonempty, then expr 2; otherwise, expr 3. 

The label is in two parts, which are separated by expr . Two adjacent two-part labels that have the same 
first part will be merged by appending the second part of the second label onto the first label separated 
by the string specified in theseparate-iabei-second-parts command (initially, a comma followed by a 
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space); the resulting label will also be a two-part label with the same first part as before merging, and so 
additional label scan be merged into it. N otethat it is permissible for the first part to be empty; this 
may bedesirableforexpressionsused in the short-label command. 

(expr) The same as ex pr . U sed for grouping. 

T he preceding expressions are listed in order of precedence (highest first); & and | have the same precedence 

MACRO INTERFACE 

Each reference starts with a call to the macro ]-. The string [f will be defined to be the label for this reference unlesstheno- 
labei-in-reference command has been given. There then follows a series of string definitions, one for each field: string [X 
corresponds to field x. The number register [p is set to i if the p field contains a range of pages. The [t, [a, and [o number 
registers are set to i according as the t, a, and o fields end with one of the characters.?!. The [e number register will beset 
to 1 if the [E string contains more than one name The reference is followed by a cal I to the n macro. The first argument to 
this macro gives a number representing the type of the reference. If a reference containsaj field, it will be classified as type 1; 
otherwise, if it containsa b field, itwill betype3; otherwise, if it contains a G orR field it will betype4, otherwise if it 
contains an i field, itwill be type 2; otherwise itwill be type 0. The second argument is a symbolic name for the type other, 
journal-article, book, articie-in-book, or tech-report. Groupsof references that have been accumulated or are produced by 
the bibliography command are preceded by a call to the ]< macro and followed by a call to the ]> macro. 

FILES 

/usr/dict/papers/ind D efault database 

fiie.i Index files 

SEE ALSO 

gindxbib(l), glookbib(l), lkbib(l) 

BUGS 

In label expressions, <> expressionsareignored inside .char expressions. 

GroffVeraor 1.09 
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grep, egrep, fgrep— Print lines matching a pattern 

SYNOPSIS 

grep [ —[[AB]] n u m ][-[CEFGVBchilnsvwx]] [-e ] pattern j -ffiI e ] [fiI e s ... ] 

DESCRIPTION 

grep searches the named input files (or standard input if no files are named, or the filename- is given) for lines containing a 
match to the given pattern. By default, grep prints the matching lines. 

T here are three major variants of grep, controlled by the following options: 

-g Interpret pat tern as a basic regular expression (see the list following this one). This is the default. 

-e Interpret pattern as an extended regular expression. 

-f Interpret patter n as a list of fixed strings, separated by newlines, any of which is to be matched. 

In addition, two variant programs, egrep and fgrep, are available, egrep issimilar (but not identical) to grepn-E, and is 
compatible with the historical UNIX egrep. Fgrep isthesameasgrepn-F. 

All variants of grep understand the following options: 



grep, egrep, fgrep 



-A num 
-B num 
-C 
-V 

-b 

-c 

-e pattern 

-f file 

-h 

-i 

-L 

-1 


-n 

-q 

-s 

-v 


-w 


M atches will be printed with num lines of leading and trailing context. H owever, grep will never print 
any given line more than once. 

Print num lines of trailing context after matching lines. 

Print num lines of leading context before matching lines. 

Equivalentto - 2 . 

Print the version number of grep to standard error. This version number should be included in all bug 
reports. 

Print the byte offset within the input file before each line of output. 

Suppress normal output; instead printacount of matching lines for each input file. With the-v 
option, count nonmatching lines. 

U se p a 11 e r n as the pattern; useful to protect patterns beginning with -. 

Obtain the pattern from f i 1 e. 

Suppress the prefixing of filenames on output when multiple files are searched. 

I gnore case distinctions i n both the pa 11 e r n and the input fi les. 

Suppress normal output; instead print the name of each input file from which no output would 
normally have been printed. 

Suppress normal output; instead print the name of each input filefrom which output would normally 
have been printed. 

P ref i x each line of output with theline number within itsinput file 
Q uiet; suppress normal output. 

Suppress error messages about nonexistent or unreadable files. 

Invert thesenseof matching, to select nonmatching lines. 

Select only those lines containing matches that form whole words. The test is that the matching 
substring must either be at the beginning of the line, or preceded by a nonword constituent character. 
Similarly, it must be either at the end of the line or followed by a nonword-constituent character. 

W ord-constituent characters are letters, digits, and the underscore. 

Select only those matches that exactly match the whole line. 


REGULAR EXPRESSIONS 

A regular expression is a pattern that descri bes a set of strings. Regular expressions are constructed analogously to arithmetic 
expressions, by using various operators to combine smaller expressions. 

grep understands two different versions of regular expression syntax: base and extended. In GN U\grep, there is no difference 
in available functionality using either syntax. In other implementations basic regular expressions are less powerful. The 
following description applies to extended regular expressions; differences for basic regular expressionsare summarized 
afterwards. 

The fundamental building blocks are the regular expressions that match a single character. M ost characters, including all 
letters and digits are regular expressions that match themselves. Any meta character with special meaning may be quoted by 
preceding it with a backslash. 

A list of characters enclosed by [ and ] matches any single character in that list; if the first character of the list is the caret (•) 
then it matches any character not in the list. For example the regular expression [0123456789] matches any single digit. A 
range of ASCII characters may be specified by giving the first and last characters, separated by a hyphen. Finally, certain 
named classes of characters are predefined. Their names are self-explanatory, and they are [: ainum: ], [: alpha:], [:cntri:], 

[: digit:], [: graph: ], [ : lower : ], [: print : ] , [ :punct : ], [: space: ], [: upper: ], and [: xdigit : ] .For example, [[: ainum: ] ] 
means [o-9A-za- z], except the latter form is dependent upon the ASC11 character encoding, whereas the former is portable. 
(N ote that the brackets in these class names are part of the symbolic names, and must be included in addition to the brackets 
delimiting the bracket list.) M ost meta characters lose their special meaning inside lists. T 0 include a literal ], place it first in 
the list. Similarly, to include a literal", place it anywhere but first. Finally, to include a literal place it last. 

The period matches any single character. The symbol \w is a synonym for [ [ :ainum: ] ] and \w is a synonym for [*[: ainum]]. 
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The caret and the dollar sign are metacharacters that respectively match the empty string at the beginning and end of a line. 
Thesymbols\< and \>, respectively, match the empty string at the beginning and end of a word. The symbol \b matches the 
empty stri ng at the edge of a word, and \b matches the empty string provi ded it's not at the edge of a word. 

A regular expression matching a single character may be followed by one of several repetition operators: 

? The preceding item is optional and matched at most once. 

* The preceding item will be matched zero or more times. 

+ The preceding item will be matched one or more times, 

n The preceding item is matched exactly n times, 

n, The preceding item is matched n or more times. 

,m The preceding item is optional and is matched at most m times, 

n ,m The preceding item is matched at least n times, but not more than m times. 

T wo regular expressions may be concatenated; the resulting regular expression matches any string formed by concatenating 
two substrings that respectively match the concatenated subexpressions. 

T wo regular expressions may be joined by the infix operator |; the resulting regular expression matches any string matching 
either subexpression. 

Repetition takes precedence over concatenation, which in turn takes precedence over alternation. A whole subexpression may 
be enclosed in parentheses to override these precedence rules. 

The back reference \n, where n is a single digit, matches the substring previously matched by then th parenthesized 
subexpression of the regular expression. 

In basic regular expressions, themeta characters |, (, and > lose their special meaning; instead usethebackslashed versions 
\?, \+, \f, \j, \(, and \>. 

In egrep, themeta character {loses its special meaning; instead use \{. 

DIAGNOSTICS 

N ormally, exit status is 0 if matches were found, and 1 if no matches were found. (The .b -v option inverts the sense of the 
exit status.) Exit status is 2 if there were syntax errors in the pattern, inaccessible input files, or other system errors 

BUGS 

E-mail bug reports to bug-gnu-utiis@prep.ai.mit.edu. Besureto include theword grep somewherein the "Subject:" field. 

Large repetition counts in them ,n construct may cause grep to use lots of memory. In addition, certain other obscure regular 
expressions require exponential time and space, and may cause grep to run out of memory. 

Back references are very slow, and may require exponential time. 

GNU Project, 10 September 1992 
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grephistery— Display filenames from Usenet history file 

SYNOPSIS 

grephistery [ -f filename ][-e ][-n ][-q ][-1 ] [-i ][-s ][ me s s a g e i d ] 

DESCRIPTION 

grephistery queries the dbz(3) index into thehistery(5) file for an article having a specified M essagelD. 

If messageid cannot be found in the database, the program prints "Not found" and exits with a nonzero status. If messageid is 
in thedatabase, the program prints the pathname and exits successfully. If no pathname exists, theprogram will print/dev/ 



grodvi 



nun and exit successfully. Thiscan happen when an article has been canceled, or if it has been expired but its history isstill 
retained. This is default behavior, which can be obtained by using the -n flag. 

If the -q flag is used, then no message is displayed. The program will still exit with the appropriate exit status. If the -e flag is 
used, then gr ephi story will only print the filename of an existing article. 

If the-iflag isused, then the enti re I inefrom the history fi le will bedisplayed. 

If the -i flag isused, then gr ephi story will read a list of M essage-IDson standard input, one per line Leading and trailing 
whitespace is ignored, as are any malformed lines. It will print on standard output thoaM essage-IDs that are not found in 
the history database. Thisflag isused in processing ihave control messages. 

If the -s flag isused, then gr ephi story will read a similar list from its standard input. It will print on standard output a list of 
filenames for each article that isstill available. Thisflag isused in processing sendme control messages. 

T o specify a different value for the history file and database, use the-f flag. 

HISTORY 

W ritten by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

dbz(3), history(5) 

grodvi 

grodvi— C onvert grott output to T eX dvi format 

SYNOPSIS 

grodvi [ -dv ][-wn ] [-Fd i r ] [files ... ] 

DESCRIPTION 

grodvi is a driver for grott that produces dvi format. N ormally, it should be run by groff-Tdvi. This will run gtrott-Tdvi; it 
will also input the macros /usr/iib/groff/tmac/tmac.dvi; if the input is being preprocessed with geqn, it will also input /usr/ 
lib/groff/font/devdvi/eqnchar. 

The dvi file generated by grodvi can be printed by any correctly written dvi driver. The troff drawing primitives are 
implemented using the tpic version 2 specials. If the driver does not support these, the \d commands will not produce any 
output. 

There isan additional drawing command available 

\d 1 Rdh dv' D raw a rule (solid black rectangle), with onecorner atthecurrent position, and the diagonally 

opposite corner atthecurrent position +<d h ,dv) . Afterwards, the current position will be at the 
opposite corner. This produces a rule in the dvi file and so can be printed even with a driver that does 
not support the tpic specials, unlike theother \d commands. 

Thegrotf command \x'anyt hi ng 1 is translated into the same command in the dvi file as would be produced by \speciai{ 
anything } in T eX; anythi ng may not contain a newline. 

Font files for grodvi can be created from tfm files using tfmtodit(l). The font description file should contain the following 
additional commands: 

internalname name The name Of the tfm file (without the .tfm extension) is name. 
checksum n T he checksum in the tfm file iSn. 

designsize n T he designsize in the tfm file iSn. 


T hese are automatically generated by tfmtodit. 
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In troff, the \n escape sequence can be used to access characters by their position in thecorrespondingtfm file; all characters 
in the ttm file can be accessed thisway. 

OPTIONS 

-d Do notusetpic specials to implement drawing commands. H orizontal and vertical lines will be implemented by 
rules. Other drawing commands will be ignored. 

-v Print the version number. 

-wn Set the default line thickness ton thousandths of an em. 

-Fd i r Search directory d i r /devdvi for font and device description files. 

FILES 

/usr/lib/groff/font/devdvi/DEsc D evicedescription file 

/usr/lib/groff/font/devdvi/ f Font description filefor font F 

/usr/lib/groff/tmac/tmac.dvi M acrOSfor use with grodvi 

BUGS 

dvi files produced by grodvi use a different resolution (57,816 units per inch) than those produced by TeX. Incorrectly 
written drivers that assume the resolution used by TeX, rather than using the resolution specified in the dvi file, will not 
work with grodvi. 

When using the-d option with boxed tables, vertical and horizontal lines can sometimes protrude by one pixel. This is a 
consequence of the way T eX requires that the heights and widthsof rules be rounded. 

SEE ALSO 

tfmtodit(l), groff(l), gtroff(l), geqn(l), groff_out(5), groff_font(5), groff_char(7) 

Groff Version 1.09 14 
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groff— Front end for the groff document formatting system 

SYNOPSIS 

groff [ -tpeszaivhblCENRVXZ] [-wname ] [ -Wn a me ][-mname ] [ -Fd i r ] [ -Td e v ] [ -f f a m ] [ -Md i r ] [-dc s ][-rcn ][-nnum ] 
[-ol i st ] [-Par g ] [f i I es ... ] 

DESCRIPTION 

groff isafront-end to thegroff document formatting system. N ormally, it runsthegtroff program and a postprocessor 
appropriate for the selected device. Available devices are 

ps F or P ostScri pt pri nters and previ ewers 
dvi For TeX dvi format 

X75 For a 75 dpi Xll previewer 

X 100 For a 100dpi Xll previewer 

ascii For typewriter-like devices 

latini For typewriter-like devices using the I SO Latin-1 character set. 

The postprocessor to be used for a device is specified by thepostpro command in the device description file. This can be 
overridden with the -x option. 

The default device is ps. It can optionally preprocess with any of gpic, geqn, gtbi, grefer, orgsoeiim. 



Options without an argument can be grouped behind asingle A filenameof - denotes the standard input. 
The grog command can be used to guess the correct groff command to use to format a file. 
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OPTIONS 

-h Print a help message. 

-e Preprocess with geqn. 

-t Preprocesswith gtbi. 

-p Preprocesswith gpic. 

-s Preprocesswith gsoelim. 

-r Preprocesswith grefer. N o mechanism is provided for passing arguments to grefer because most greter options 

have equivalent commands that can beincluded in thefile. Seegrefer(l) for more details 
-v M ake programs run by groff print out their version number. 

-v Print the pipeline on stdout instead of executing it. 

-z Suppress output from gtroff. 0 nly error messages will beprinted. 

-z Do not postprocess the output of gtroff. N ormally, groff will automatically run the appropriate postprocessor. 

-pa r g Passarg to the postprocessor. Each argument should be passed with a separate-p option. N ote that groff does not 

prepend - to ar g before passing it to the postprocessor. 

-l Send the output to a printer. The command used for this is specified by the print command in the device 
description file 

-La r g Passarg to the spooler. Each argument should be passed with a separate -l option. N ote that groff does not 
prepend - to ar g before passing it to the postprocessor. 

-Tdev Prepare output for devicede v . T he default device is ps. 

-x Preview with gxditview instead of using the usual postprocessor. This is unlikely to produce good results except 

with -Tps. 

-n Don't allow newlines with eqn delimiters. This is the same as the -n option in geqn. 


The options -a, -b, -i, -C, -E, -wna me, -Wna me, -mil a me, -ol i s t, -dcs, -rc n, -Fdi r, -Md i r, -ff a m, 3nd -nn u m are descri bed in 
gtroff(l). 


ENVIRONMENT 

GROFF_COMMAND_PREFIX 

GROFF_TMAC_PATH 

GROFF_TYPESETTER 

GROFFFONTPATH 

PATH 

GROFF_TMPDIR 


If this is set X, then groff will run Xtroff instead Of gtroff. This also applies to tbl, pic, eqn, refer, 
and soelim. It does not apply to grops, grodvi, grotty, and gxditview. 

A co I on-separated list of directories in which to search for macro files. 

D efault device. 

A colon-separated list of directories in which to search forthedevname directory. 

T he search path for commands executed by groff. 

The directory in which temporary files will be created. If this is not set and tmpdir is set, temporary 
files will be created in that directory. Otherwise temporary files will be created in /tmp. The 
grops(l) and grefer(l) commands can create temporary files. 


FILES 

/usr/iib/groff/font/devname / desc D evice description file for device name. 
/usr/lib/groff/font/devnam^F Font filefor font F of devicename. 

AUTHOR 

James Clark (jjc@jciark.com) 
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BUGS 

Report bugs to bug-groff@prep.ai.mit.edu. I nclude a complete, self-contained example that will allow the bug to be 
reproduced, and say which version of groff you are using. 

COPYRIGHT 

Copyright 1989,1990,1991,1992 FreeSoftwareFoundation, Inc. 

groff is free software; you can redistri bute it or modify it under the terms of the G N U General Public License as published 
by the Free Software Foundation; either version 2, or (at your option) any later version. 

groff is distributed in the hope that itwill be useful, but without any warranty; without even theimplied warranty of 
merchantability or fitness for a particular purpose. See the GN U General Public License for more details. 

You should have received a copy of theGN U General Public License along with groff; see the file copying. If not, write to 
the Free Software Foundation, 675 M assAve, Cambridge, M A 02139, USA. 

AVAILABILITY 

The most recent released version of groff is always avail able for anonymous ftp from prep.ai.mit.edu (18.71.0.38) in the 
directory pub/gnu. 

SEE ALSO 

grog(l), gtroff(l), gtbl(l), gpic(l), geqn(l), gsoelim(l), grefer(l), grops(l), grodvi(l), grotty(l), gxditview(l), 
groff_font(5), grof_out(5), groff_ms(7), groff_me(7), groff_char(7) 

Groff Verson 1.09, 29 October 1992 
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grog— Guess options for groff command 

SYNOPSIS 

grog [ -option ... ] [f i I es ... ] 

DESCRIPTION 

grog reads f i i es and guesses which of the groff (1) options -e, -man, -me, -mm, -ms, -p, -s,and -t are required for printing 
f i i es, and prints the groff command including those options on the standard output. A filename of - is taken to refer to the 
standard input. If no files are specified, the standard input will be read. Any specified options will be included in the printed 
command. N o space is allowed between options and their arguments. For example, 

'grog -Tdvi paper.ms 1 

will guess the appropriate command to print paper, ms and then run it after adding the -Tdvi option. 

SEE ALSO 

doctype(l), groff(l), gtroff(l), gtbl(l), gpic(l), geqn(l), gsoelim(l) 

Groff Version 1.09 14 
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grops— PostScript driver for groff 

SYNOPSIS 

grops [ -glv ][-bn ][-on ][-wn ][ -Fd i r ] [f jIe s ... ] 
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DESCRIPTION 

grops translates the output of GN U troft to PostScript. N orm ally, grops should be invoked by using the grotf command 
with a-Tps option. If no files are given, grops will read the standard input. A filename of - will also cause grops to read the 
standard input. PostScript output is written to the standard output. When grops is run by grotf, options can be passed to 
grops by using the grotf -p option. 

OPTIONS 

-bn Workaround broken spoolers and previewers. N orm ally grops produces output that conforms the Document 

Structuring Conventions version 3.0. Unfortunately, some spoolers and previewers can't handle such output. The 
valueofn controls what grops does to its output acceptable to such programs. A value of 0 will causegrops not to 
employ any workarounds. Add 1 if no %%BeginDocumentsetup and %%EndDocumentsetup comments should be 
generated; this is needed for early versions of T ranScript that get confused by anything between the%%EndProiog 
comment and the first %%Page comment. Add 2 if lines in included files beginning with %i should be stripped out; 
this is needed for Sun's pageview previewer. Add 4 if %%Page, %%Traiier, and %%EndProiog comments should be 
stripped out of included files; this is needed for spoolers that don't understand the%%BeginDocument and 
%%EndDocument comments. Add 8 if the first line of the PostScript output should be %!Ps-Adobe -2.0 rather than 
%i ps -Adobe -3.0; this is needed when using Sun's N ewsprint with a printer that requires page reversal. The default 
value can be specified by abrokenn command in theDEsc file. Otherwise, the default value is 0. 

-cn Print n copies of each page. 

-g Guess the page length. This generates PostScript code that guesses the page length. The guess will be correct only 
if the i mageable area is vertically centered on the page. This option allows you to generate documents that can be 
printed both on letter (8.5x11) paper and on A4 paper without change. 

-1 Print the document in landscape format. 

-Fdi r Search the directory di r/devn a me for font and da/ice description files; name isthenameof the device, usually ps. 

-wn Linesshould bedrawn using a thickness of n thousandthsof an em. 

-v Print the version number. 

USAGE 

There are styles cal led r, i, b, and bi mounted at font positions 1 to 4. The fonts are grouped into families a, bm, c, h, hn, n, 
p, and t having members in each of these styles: 

ar AvantGarde-Book 

ai AvantGarde-BookOblique 

ab AvantGarde-Demi 

abi AvantGarde-DemiOblique 

bmr Bookman-Light 

bmi Bookman-Lightl talic 

bmb Bookman-Demi 

bmbi Bookman-Demiltalic 

cr Courier 

ci Courier-Oblique 

cb Courier-Bold 

cbi Courier-BoldOblique 

hr Helvetica 

hi Helvetica-Oblique 

hb H elvetica-Bold 

hbi H elvetica-BoldO blique 

hnr H el vetica-N arrow 

hni Helvetica-Narrow-Oblique 
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hnb H el vetica-N arrow- Bold 

hnbi H elvetica-N arrow-BoldO blique 

nr N ewCenturySchlbk-Roman 

ni N ewC entu rySchlbk-ltalic 

nb N ewCenturySchlbk-Bold 

nbi N ewC enturySchlbk-Boldl talic 

pr Palatino-Roman 

pi Palatino-ltalic 

pb Palatino-Bold 

pbi Palatino-Boldltalic 
tr Times-Roman 

ti T imes-ltalic 

tb Times-Bold 

tbi Times-Boldltalic 

T here is also the following font which is not a member of a family: 
zcmi Z apf Chan eery-M ediuml talic 

There are also some special fonts called ss and s. Zapf D i n gbats is avail able as zd and a reversed version of ZapfD ingbats 
(with symbols pointing in the opposite direction) is avail able as zdr; most characters in these fonts are unnamed and must be 
accessed using \n. 

grops understands various x commands produced using the \x escape sequence; grops will only interpret commands that 
begin with a ps: tag. 

\x 1 ps : e x e c code' This executes the arbitrary PostScript commands in code. T he PostScript currentpoint will be set to 

the position of the\nx command before executing code. The origin will be at the top left corner of 
the page, and y coordinates will increase down the page. A procedure u will be defined that converts 
groft units to the coordinate system in effect. For example, 

\X'ps: exec \nx u 0 rlineto stroke' 

will draw a horizontal lineoneinch long, code may make changes to thegraphics state, but any 
changes will persist only to the end of the page. A dictionary containing the definitions specified by 
def and mdet will beon top of the dictionary stack. If your code adds definitions to this dictionary, 
you should allocate space for them using \x' psmdef n ■. Any definitions will persist only until the end 
of the page. If you use the \y escape sequence with an argument that names a macro, code can 
extend over multiple lines. For example, 

.nr x 1i 

.de y 

ps: exec 

\nx u 0 rlineto 

stroke 

\Yy 

is another way to draw a horizontal lineoneinch long. 

\x'ps:f i ename 1 T his is the same as the exec command except that the PostScript code is read from filename. 

\x'ps:def code 1 Place a PostScript definition contained in code in the prologue. There should beat most one 

definition per \x command. Long definitions can be split over several \x commands; all the code 
arguments are simplyjoined together separated by newlines. Thedefinitionsare placed in a 
dictionary which is automatically pushed on the dictionary stack when an exec command is 
executed. If you usethe\Y escape sequence with an argument that names a macro, code can extend 
over multiple lines. 
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Like def, except that code may contain up to n definitions, grops needs to know how many 
definitionscode contains so that it can create an appropriately sized PostScript dictionary to contain 
them. 

Import a PostScript graphic from file. The arguments iix, iiy, urx, and ury give the bounding box 
of the graphic in the default PostScript coordinate system; they should all be integers; iix and iiy 
are the x and y coordinates of the lower-1 eft corner of the graphic; urx and ury are the x and y 
coordinates of the upper-right corner of the graphic; wi dth and hei ght are integers that give the 
desired width and height in groff units of the graphic. The graphic will be scaled so that it has this 
width and height and translated so that the lower-left corner of the graphic is located at the 
position associated with \x command. If the height argument is omitted, it will be scaled uniformly 
in thex and y directions so that it has the specified width. N ote that the contents of the \x 
command are not interpreted bytroff; so vertical space for the graphic is not automatically added, 
and thewidth and height arguments are not allowed to have attached scaling indicators. If the 
PostScript file complies with the Adobe Document Structuring Conventions and contains a 
%%BoundingBox comment, then the bounding box can be automatically extracted from within groff 
by using the sy request to run thepsbb command. 

The -mps macros (which are automatically loaded when grops is run by the groff command) include a pspic macro that 
allows a picture to be easily imported. This has the format: 

.PSPIC file [ -L j -R j -I n ][width [ height ]] 

file is the name of the file containing the illustration; wi dth and hei ght give the desired width and height of the graphic. The 
wi dth and hei ght arguments may have scaling indicators attached; the default scaling indicator is i. This macro will scale the 
graphic uniformly in the x and y directions so that it is no more than wi dth wide and hei ght high. By default, the graphic will 
be horizontally centered. The -l and -r cause the graphic to be left-aligned and right-aligned, respectively. The- 1 option 
causes the graphic to be indented byn. 

\x 1 ps: mvis 1 , \x 1 ps: endinvis 1 N o output will be generated for text and drawing commands that are bracketed with 

these\X commands. T hese commands are intended for use when output from troff wi II 
be previewed before being processed with grops; if the previewer isunableto display 
certain characters or other constructs then other substitute characters or constructs can 
be used for previewing by bracketing them with these \x commands. 

For example, gxditview is not able to display a proper \(em character because the standard X11 fonts do not provide it; this 
problem can be overcome by executing the following request: 

.char \(em \X'ps: invis'\ 

\Z'\v'-.25m'\h'.05m 1 \D'1 .9m 0 , \h'.05m"\ 

\X'ps: endinvis'\(em 

In thiscase, gxditview will beunableto display the \ (em character and will draw theline, whereasgrops will print the \ (em 
character and ignore the line. 

The input to grops must be in the format output by gtroff(l). This is described in groff_out(l). In addition, the device and 
font description files for the device used must meet certain requirements. The device and font description files supplied for 
ps device meet all these requirements, afmtodit(l) can be used to create font files from afm files. The resolution must bean 
integer multiple of 72 times the sizescale. T heps device uses a resolution of 72000 and a sizescale of 1000. The device 
description file should contain a command: 

paperlengthn 

which says that output should be generated that is suitable for printing on a page whose length isn machine units Each font 
description file must contain a command: 
internalnameps name 

which says that the PostScript name of the font is ps name. It may also contain a command: 
encodingenc file 


\X'ps:mdef ncode 


\X'ps:importfile 
llxllyurxurywidth 
[height]' 
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which says that the PostScript font should be reencoded using the encoding described in enc_f i i e ; thisfileshould consist of a 
sequence of li nes of the form: 

pschar code 

wherepschar is the PostScript name of the character, and code is its position in the encoding expressed asadecimal integer. 
The code for each character given in the font file must correspond to the code for the character in encoding file, or to the 
code in the default encoding for the font if the PostScript font is not to be reencoded. This code can be used with the\N 
escape sequence in trott to select the character, even if the character does not haveagroff name. Every character in the font 
file must exist in the PostScript font, and the widths given in the font file must match the widths used in the PostScript font, 
grops will assume that a character with agroff name of space is blank (makes no marks on the page); it can make use of such 
a character to generate more efficient and compact PostScript output. 

grops can automatically include the down loadable fonts necessary to print the document. Any downloadable fonts which 
should, when required, beincluded by grops must be listed in thefile/usr/iib/groff/font/devps/downioad; thisshould 
consist of lines of the form: 

font f i I e n a me 

where font is the PostScript name of the font, and f i i ename is the name of the file containing the font; lines beginning with # 
and blank lines are ignored; fields may be separated by tabs or spaces; f i i ename will be searched for using the same mecha¬ 
nism that is used forgrott font metric files. The download file itself will also be searched for using this mechanism. 

If the file containing a down loadable font or imported document conforms to the Adobe D ocument Structuring C onven- 
tions, then grops will interpret any comments in the files sufficiently to ensure that its own output is conforming. It will also 
supply any needed font resources that are listed in the download file as well as any needed file resources. It is also able to 
handle interresource dependencies. For example, suppose that you have a downloadable font called Garamond, and also a 
downloadable font called Garamond-Outlinethat depends on Garamond (typically, it would be defined to copy Garamond's 
font dictionary, and change the PaintType), then it is necessary for Garamond to appear before Garamond-Outline in the 
PostScript document, grops will handle this automatically provided that the downloadable font file for Garamond-Outline 
indicates its dependence on Garamond by means of the Document Structuring Conventions, for example by beginning with 
the following lines: 

%!PS-Adobe-3.0 Resource-Font 
%%DocumentNeededResources: font Garamond 
%%EndComments 

%%IncludeResource: font Garamond 

In this case, both Garamond and Garamond-Outline would need to be listed in the download file A downloadable font 
should not include its own name in a%%DocumentsuppiiedResources comment. 

grops will not interpret %%DocumentFonts comments 

The%%DocumentNeededResources, %%DocumentSuppliedResources, %%IncludeResource, %%BeginResource, and %%EndResource 
Comments (or possibly the old %%DocumentNeededFonts, %%DocumentSuppliedFonts, %%IncludeFont, %%BeginFont, and %%EndFont 
comments) should be used. 

FILES 

/usr/lib/groff/font/devps/DESC 
/usr/lib/groff/font/devps/F 
/usr/lib/groff/font/devps/download 
/usr/lib/groff/font/devps/text.enc 
/usr/lib/groff/tmac/tmac.ps 
/usr/lib/groff/tmac/tmac.pspic 
/usr/lib/groff/tmac/tmac.psold 

/usr/lib/groff/tmac/tmac.psnew 
/tmp/gropsXXXXXX 


Devicedescription file 
Font description file for font F 
List of downloadable fonts. 

Encoding used for text fonts 

M acros for use with grops; automatically loaded by troffrc 
Definition of pspic macro, automatically loaded bytmac.ps 
M acrosto disable use of characters not present in older PostScript printers; 
automatically loaded bytmac.ps 
M acrosto undo the effect of tmac.psoid 
T emporary file 
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SEE ALSO 

afmtodit(l), groff(l), gtroff(l), psbb(l), groff_out(5), groff_font(5), groff_char(7) 

Groff Version 1.09,14 February 1995 
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grotty— groft driver for typewriter-like devices 

SYNOPSIS 

grotty [ -hfbuodBUv ][-Fdir ] [files ... ] 


DESCRIPTION 

grotty translates the output of GNU trotf into aform suitable for typewriter-like devices. N ormally, grotty should invoked 
by using the groft command with a -Tascii or -Tiatim option. If no files are given, grotty will read the standard input. A 
filenameof - will also causegrotty to read thestandard input. Output iswritten to the standard output. 

N ormally, grotty prints a bold character c using the sequence 'c backspace c 1 and an italic character c by the sequence 
'-Backspace c' . These sequences can be displayed on a terminal by piping through ui(l). Pagers such asmore(l) or less(l) 
are also able to display these sequences. U se either -b or-u when piping into iess(l); use -b when piping into more(l). There 
is no need to filter the output through coi(l) si nee grotty never outputs reverse linefeeds. 

The font description file may contain a command: 

internalnamen 

where n is a decimal integer. If the 01 bit in n is set, then thefontwill be treated as an italic font; if the 02 bit is set, then it 
will be treated as a bold font. The code field in the font description field gives the code that will be used to output the 
character. This code can also be used in the\N escape sequence in trotf. 


OPTIONS 

-Fd i r Search the directory di r /devname for font and da/ice description files; name is the name of the device, usually ascii 
Oflatinl. 

-h Use horizontal tabs in the output. T abs are assumed to beset every 8 columns 

-t Use form feeds in the output. A form feed will be output at the end of each page that has no output on its last 

line. 

-b Suppress the use of overstriking for bold characters. 

-u Suppress the use of underlining for italic characters. 

-b U se only overstriking for bold-italic characters. 

-u U se only underlining for bold-italic characters. 

-o Suppress overstriking (other than for bold or underlined characters). 

-d I gnore all \D commands. W ithout this, grotty will render \d ■ l ...' commands that have at least one zero 
argument (and so are either horizontal or vertical) using-, ;, and + characters. 

-v Print the version number. 


FILES 

/ usr/lib/groft/font/devascii/DESC 
/usr/lib/groff/font/devascii/F 
/usr/lib/groff/font/devlatinl/DESC 
/usr/lib/groff/font/devlatinl/F 
/usr/lib/groff/tmac/tmac.tty 
/usr/lib/groff/tmac/tmac.tty-char 


Device description filefor ascii device 
Font description file for font f of ascii device 
Device description filefor latini device. 

Font description filefor font f ofiatini device. 

M acrosforusewith grotty. 

Additional kludgy character definitions for use with grotty. 
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BUGS 

grotty is intended only for simple documents 

There is no support for fractional horizontal or vertical motions. 

There is no support for \d commands other than horizontal and vertical lines. 

Characters above the first line (that is, with avertical position of 0 ) cannot be printed. 

SEE ALSO 

groff(l), gtroff(l), groff_out(5), groff_font(5), groff_char(7), ul(l), more(l), less(l) 

Groff Versonl.09,14 February 1995 
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gsoeiim— Interpret .so requests in grott input 

SYNOPSIS 

gsoelim [ -Cv ] [f i I es ... ] 

DESCRIPTION 

gsoelim readsf i 1 es and replaces lines of the form 
.sofile 

by the contents of fi 1 e. It is useful if files included with so need to be preprocessed. N ormally, gsoelim should be invoked 
with the-s option of grott. 

OPTIONS 

-c Recognize .so even when followed by a character other than space or newline 
-v Print the version number 

SEE ALSO 

groff(l) 

GroffVersonl.09,15 September 1992 


gtbl 

gtbi— Format tables for trott 

SYNOPSIS 

gtbl [ -Cv ] [fiI es ... ] 

DESCRIPTION 

This manual page describes the GN U version oftbi, which is part of the grott document formatting system, tbi compiles 
descriptions of tables embedded within trott input files into commands that are understood by trott. N ormally, it should 
be invoked using the -t option of grott. It is highly compatible with UNIX tbi. The output generated by GN U tbi cannot 
be processed with UNIX trott; it must be processed with GNU trott. If no files are given on the command line, the 
standard input will be read. A filename of - will cause the standard input to be read. 
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OPTIONS 

-c Recognize .ts and .te a/en when followed by a character other than space or newline 
-v Print the version number 

USAGE 

Only the differences between GNU tbi and U NIX tbi are described here. 

N ormally, tbi attempts to prevent undesirable breaks in the table by using diversions. This can sometimes interact badly 
with macro packages' own use of diversions, when footnotes, for example, are used. The nokeep option tells tbi not to try to 
prevent breaks in thisway. 

T he decimaipoint option specifi es the character to be recognized as the decimal point character in place of the default period. 
It takes an argument in parentheses, which must be a single character, as for the tab option. 

Thet format modifier can be followed by an arbitrary length font name in parentheses. 

There is ad format modifier that meansthat a vertically spanning entry should be aligned at the bottom of its range. 

There is no limit on the number of columns in a table, nor any limit on the number of text blocks All the lines of a table are 
considered in deciding column widths not just the first 200. T able continuation (,t&) lines are not restricted to the first 200 
lines. 

N umeric and alphabetic items may appear in the same column. 

N umeric and alphabetic items may span horizontally. 

tbi uses register, string, macro and diversion names beginning with 3. When usingtbi, you should avoid using any names 
beginningwith a 3. 

BUGS 

You should use .tsh/.th in conjunction with a supporting macro package for all multi page boxed tables. If there is no header 
that you want to appear at the top of each page of the table, place the .th line immediately after the format section. Do not 
enclose a multi page table within keep/release macros, or divert it in any other way. 

A text block within a table must be ableto fit on one page. 

The bp request cannot be used to force a page-break in a multi page table Instead, defineBP as follows: 

.de BP 

.ie 1 \\n(.z" .bp \\$1 
.el \!.BP \\$1 


and use bp instead of bp. 

SEE ALSO 

groff(l), gtroff(l) 

Groff Version 1.09,1 April 1993 


gtroff 

gtrotf— Format documents 

SYNOPSIS 


gtroff [-abivzCER] [-w name ] [-W name ] [-d cs] [-f f am] [-m name ] [-n num] [-0 I i st ] [-r cn] [-T name ] [-F di r ] [-M 
dir] [nf i I es . .. n] 
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DESCRIPTION 

This manual page describes the G N U version of troff, which is part of thegroff document formatting system. It is highly 
compatible with U N IX troff. Usually, it should be invoked using thegroff command, which will also run preprocessors and 
postprocessors in the appropriate order and with the appropriate options. 

OPTIONS 

-a Generate an ASCII approximation of the typeset output. 

-b Print a backtrace with each warning or error message. This backtrace should help track down the cause of 

the error. T he line numbers given in the backtrace may not always correct: troff 's idea of line numbers 
gets confused by as or am requests. 

-i Read the standard input after all the named input files have been processed. 

-v Print the version number. 

-wn a me E nable warning name . A vai lablewarni ngs are described in the "Warnings" subsection as follows. M ultiple 

-w options are allowed. 

-wna me I nhibit warning name. M ultiple -w options are allowed. 

-e Inhibit all error messages. 

-z Suppress formatted output. 

-c E nable compatibi lity mode. 

-dcs, -dn a me =s D efi nec or na me to be a string s ; c must be a one-letter name. 

-ff am Use fan as the default font family. 

-mna me Read i n the fi le tmac.name . N OPTially, this will be Searched for in /usr/lib/grof f/tmac. 

-R D On't load troff rc. 

-nnum N umber the first pagenum. 

-oi i st Output only pages in list, which is a comma-separated list of page ranges; n means print pagen, m-n 

means print every page between m and n, -n means print every pageup to n, n- means print every page 
from n. Troff will exit after printing the last pagein the list. 

-rcn, -rname=n Set number register c or name to n; c must be a one-character name; n can beany troff numeric expression, 

-m a me P repare output for devi ce n a me , rather than the defau11 ps. 

-Fd i r Search di r for subdirectories devname (name is the name of the device) for the desc file and font files before 

the normal /usr/lib/groff/font. 

-Mdir Search directory di r for macro files before the normal /usr/iib/groff/tmac. 

USAGE 

Only the features not in UNIX troff are described here. 

LONG NAMES 

T he names of number registers, fonts, strings/macros/diversions, special characters can be of any length. I n escape 
sequences, where you can use (** for a two-character name, you can use [*** ] for a nameof arbitrary length: 

\ [xxx ] Print the special character called **x. 

\f [x xx ] Set font xxx. 

\*[xxx ] I nterpolate string xxx. 

\n [x x x ] Interpolate number register xxx. 

FRACTIONAL POINT SIZES 

A scaled point is equal to 1/sizescale points, where sizescale is specified in the desc file (i by default.) There is a new scale 
indicator z that has the effect of multiplying by sizescale. Requests and escape sequences in troff interpret arguments that 
represent a point size as being in units of scaled points but they evaluate each such argument using a default scale indicator 
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of z. Arguments treated in this way are the argument to theps request, the third argument to thecs request, the second and 
fourth arguments to thetkf request, the argument to the \h escape sequence, and those variants of the \s escape sequence 
that take a numeric expression as their argument. 

For example, suppose sizescale is 1,000; then a scaled point will be equivalent to a millipoint; the request .ps 10.25 is 
equivalent to .ps 10 . 252 , and so sets the point size to 10,250 scaled points which is equal to 10.25 points. 

The number register \n(.s returns the point size in points as decimal fraction. There is also a new number register \n[ .ps] 
that returns the pointsizein scaled points 

It would make no sense to use the z scale indicator in a numeric expression whose default scale indicator was neither u nor z, 
and so troft disallows this. Similarly, it would make no sense to use a scaling indicator other than z or u in a numeric 
expression whosedefaultscaleindicatorwasz, and so trotf disallowsthisaswell. 

There is also new scale indicator s that multiplies by the number of units in a scaled point. So, for example, \n[.ps]s is equal 
to im. Be sure not to confuse the s and z scale indicators. 

NUMERIC EXPRESSIONS 

Spaces are permitted in a number expression within parentheses. 
m indicates a scale of hundredths of an em. 
e 1 >?e 2 Themaximum ofei ande 2 . 

e 1 <?e 2 Theminimum of ei ande 2 . 

(c ;e) Evaluatee usingc asthedefault scaling indicator. Ifc ismissing, ignore scaling indicators in the evaluation 

Of e. 

NEW ESCAPE SEQUENCES 

\A'a nyt hi ng 1 T his expands to i or 0 according to whether any t hi ng is or is not acceptable as the name of a string, 

macro, diversion, number register, environment, orfont. It will return 0 if a nyt hi ng isempty.This 
is useful if you want to look up user input in some sort of associative table. 

\c 1 x x x 1 T ypeset character named **x. N ormally it is more convenient to use \ [xxx ]. But \c has the 

advantage that it is compatible with recent versions of U N IX and is available in compatibility 
mode. 

\e This is equivalent to an escape character, but it's not interpreted in copy mode. For example, 

strings to start and end superscripting could be defined like this: 

.ds { \v'-.3m l \s'\En[.s]*6u/10u l 
.ds { \s0\v 1 ,3m' 

The use of \e ensures that these definitions will work even if \*t gets interpreted in copy-mode (for example by being used 
in a macro argument). 

\n 1 n 1 Typeset the character with coden in the current font, n can beany integer. M ost devices only have 

characters with codes between 0 and 255. If the current font does not contain a character with that 
code, special fonts will not be searched. The \n escape sequence can be conveniently used on 
conjunction with the char request: 

.char \[phone] \f(ZDnN'37' 

Thecodeof each character isgiven in thefourth column in thefont description file after the 
charset command. It is possible to include unnamed characters in thefont description file by using 
a name of —; the \n escape sequence is the only way to use these. 

\R'namen' T his has the Same effect as .nrnamen 

\s(nn Set thepoint sizeto nn points; nn must be exactly two digits. 

\s[n], \s 1 n 1 Set the point sizeto n scaled points: n is a numeric expression with a default scale indicator of z. 

\vx\ v(xx \ v [x x x ] I nterpolatethe contents of theenvironment variablexxx, asreturned bygetenv(3). \v is interpreted 

in copy-mode. 
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\Yx\ Y(xx \Y[xxx] 


\Z'anythi ng 1 

\$0 

\$* 

\$@ 

\$( nn, \$[ nnn ] 


\?anything\? 


\/ 


\) 

r 

\# 


This is approximately equivalent to \x 1 \* [xxx ] 1 . H owa/er, the contents of the string or macro xxx 
are not interpreted; also, it is permitted for xxx to have been defined as a macro and thus contain 
newlines (it is not permitted for the argument to \x to contain newlines). The inclusion of newlines 
requires an extension to the U NIX troff output format and will confuse drivers that do not know 
about this extension. 

Print anything and then restore the horizontal and vertical position; a nyt hi ng may not contain tabs 
or leaders. 

The name by which the current macro was invoked. T heals request can make a macro have more 
than one name 

I n a macro, the concatenation of all the arguments separated by spaces. 

In a macro, the concatenation of all theargumentswith each surrounded by double quotes, and 
separated by spaces. 

In a macro, thisgivesthennth or nnnth argument. M acroscan have an unlimited number of 
arguments. 

When used in a diversion, this will transparently embed a nyt hi ng in the diversion, anythi ng is read 
in copy mode. W hen the diversion is reread, anythi ng will be interpreted, anythi ng may not contain 
newlines; use \i if you want to embed newlines in a diversion. The escape sequence\? is also 
recognized in copy mode and turned into a single internal code; it isthiscodethat terminates 
anythi ng. Thus 
.nr x 1 
.nf 
.di d 

\?\\?\\\\?\\\\\\\\nx\\\\?\\?\? 

.di 

.nr x 2 
.di e 
.d 
.di 

.nr x 3 
.di f 
.e 
.di 

.nr x 4 
.f 

will print 4. 

This increases the width of the preceding character so that the spacing between that character and 
thefollowing character will be correct if thefollowing character is a Roman character. For example, 
if an italic f is immediately followed byaRoman right parenthesis, then in many fonts the top right 
portion of the f will overlap the top left of the right parenthesis, producing/), which is ugly. 
Inserting \i produces and avoids this problem. It is a good idea to use this escape sequence 
whenever an italic character is immediately followed by a Roman character without any intervening 
space. 

This modifies the spacing of thefollowing character so that the spacing between that character and 
the preceding character will correct if the preceding character is a Roman character. For example, 
inserting \, between the parenthesis and the/changes to (f. It is a good idea to use this escape 
sequence whenever a Roman character is immediately followed by an italic character without any 
intervening space. 

Like \& except that it behaves like a character declared with thecfiags request to be transparent for 
the purposes of end-of-sentence recognition. 

This produces an unbreakable space that stretches like a normal interword space when a line is 
adjusted. 

Everything up to and including the next newline is ignored. This is interpreted in copy mode. This 
islike \% except that \% does not ignore theterminating newline. 
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NEW REQUESTS 

.alnxx yy 

.alsxx yy 


.asciifyxx 


.backtrace 

.break 

.cflagsnc1c2. 

1 

2 

4 

8 

16 

32 


.charcst r i ng 



Create an alias** for number register object named yy. The new name and the old name will be 
exactly equivalent. If yy is undefined, a warning of typereg will be generated, and the request will 
be ignored. 

Create an alias** for request, string, macro, or diversion object named yy. The new nameandthe 
old namewill be exactly equivalent (it issimilar to a hard rather than a soft link). If yy is unde¬ 
fined, a warning of type mac will be generated, and the request will beignored. Thede, am, di, da, 
ds, and as requests only create a new object if the name of the macro, diversion, or string diversion 
is currently undefined or if it is defined to be a request; normally, they modify the value of an 
existing object. 

This request only exists in order to make it possible to make certain gross hacks work with GNU 
troft. It unformats the diversion ** in such away that ASCII characters that were formatted and 
diverted into ** will be treated likeordinary input characters when ** is reread. For example this: 

.tr @. 

.di x 
@nr\n\1 
.br 
.di 

.tr @@ 

.asciify x 
.x 

will set register n to i. 

Print a backtrace of the input stack on stderr. 

Break out of awhile loop. See also the while and continue requests. Besure notto confuse thiswith 
the br request. 

Charactersci, c2, ... have properties determined by n, which isoRed from the following. 

The character ends sentences. (Initially, characters.?! have this property.) 

Lines can be broken before the character (initially, no charactershavethisproperty); a linewill not 
be broken at a character with this property unless the characters on each side both have nonzero 
hyphenation codes. 

Lines can be broken after the character (initially, characters-\ (hy\{em have this property); a line 
will not be broken at a character with this property unless the characters on each side both have 
nonzero hyphenation codes. 

The character overlaps horizontally (initially, characters \<ui\(rn\(ru have this property). 

T hecharacter overlaps vertically (initially, character \ (br hasthisproperty). 

An end-of-sentence character followed by any number of characters with this pro perty will be 
treated as the end of a sentence if followed by a newline or two spaces; in other words, the character 
is transparent for the purposes of end-of-sentence recogniti on; this is the same as havi ng a zero 
space factor in TeX (initially, characters 1 ) ]*\(dg\ (rq have this pro perty). 

Define character c to bestring. Every time character* needsto be printed, stri ng will be processed 
in a temporary environment and the result will bewrapped up into a single object. Compatibility 
mode will be turned off and the escape character will be set to \ whilestring is being processed. 
Any emboldening, constant spacing, or track kerning will be applied to this object rather than to 
individual characters in stri ng. A character defined by this request can be used just like a normal 
character provided by the output device. In particular, other characters can betranslated to it with 
thetr request; it can be made the leader character by theic request; repeated patterns can be drawn 
with the character by using the u and \l escape sequences; words containing the character can be 
hyphenated correctly, if the hcode request is used to give the character a hyphenation code. There is 
a special antirecursion feature Use of character within the character's definition will be handled 
like normal characters not defined with char. A character definition can be removed with therchar 
request. 
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.chopxx 

.closest ream 

.continue 

.cpn 

.doxxx 

.famxx 

.fspecialf sis 2 ... 

.ftrf g 

.hcodec1codelc2code2 

.hlal ang 

.hlmn 

.hpff i I e 


.hymn 


.hysn 


.kernn 
.msof i I e 

.nroff 

.openst r eamf i I ena me 


Chop the last character off macro, string, or diversion xx . This is useful for removing the newline 
from the end of diversions that are to be interpolated as strings. 

Close the stream named stream; stream will no longer bean acceptable argument to the write 
request. See the open request. 

Finish the current iteration of awhile loop. See also thewhiie and break requests. 

If n is nonzero or missing, enable compatibility mode; otherwise, disable it. In compatibility mode, 
long names are not recognized, and the incompatibilities caused by long names do not arise. 
Interpret, xxx with compatibility mode disabled. For example, .do fam t would have the same 
effect as. tam t except that it would work even if compatibility mode had been enabled. Notethat 
the previous compatibility mode is restored before any files sourced by xxx are interpreted. 

Set the current font fami ly to xx . T he current font family is part of the current environment. See 
the description of the sty request for more information on font families. 

When the current font is f , fonts s 1 , s 2 , ... will be special; that is, they will searched for 
characters not in the current font. Any fonts specified in the special request will be searched after 
fonts specified in thetspeciai request. 

Translate font f to g. Whenever a font named f is referred to in \f escape sequence, or in the ft, 
ui, bd, cs, tkf, special, fspeciai, tp, or sty requests, font g will be used. If g is missing, or equal to 
f , then font f will not be translated. 

Set the hyphenation code of character a to code 1 and that of c 2 to code 2 . A hyphenation code must 
be a single input character (not a special character) other than a digit or a space. Initially, each 
lowercase letter has a hyphenation code, which is itself, and each uppercase letter has a hyphenation 
code which is the lowercase version of itself. See also the hpf request. 

Set the current hyphenation language to 1 ang. FI yphenation exceptions specified with thehw 
request and hyphenation patterns specified with the hpf request are both associated with the 
current hyphenation language. T he hia request is usually i nvoked by the troff rc file. 

Set the maximum number of consecutive hyphenated lines ton. If n is negative, there is no 
maximum. The default value is- 1 . This value is associated with the current environment. Only 
lines output from an environment count towardsthe maximum associated with that environment. 
Hyphens resulting from \% are counted; explicit hyphens are not. 

Read hyphenation patterns from file; this will be searched for in the same way that tmac. name is 
searched for when the -mname option is specified. It should have the same format as the argument to 
the \ patterns primitive in T eX; the letters appearing in this file are interpreted as hyphenation 
codes. A % character in the patterns file introduces a comment that continues to the end of the line. 
The set of hyphenation patterns is associated with the current language set by thehia request. The 
hpf request is usually invoked by the troffrc file 

Set the hyphenati on margin to n : when the current adjustment mode is noth, the line will not be 
hyphenated if the line is no more than n short. The default hyphenation margin iso. The default 
scaling indicator for this request is m. The hyphenation margin is associated with the current 
environment. The current hyphenation margin is available in the \n[. hym] register. 

Set the hyphenati on space to n : when the current adjustment mode is b, don't hyphenate the line if 
the line can be justified by adding no more than n extra space to each word space. The default 
hyphenation space iso. The default scaling indicator for this request is m. The hyphenation space is 
associated with the current environment. The current hyphenation space is avail able in the 
\n[.hys] register. 

If n isnonzero or missing, enable pairwise kerning; otherwise, disableit. 

The same as the so request except that f i 1 e is searched for in the same way that tmac. name is 
searched for when the-mname option is specified. 

M akethen built-in condition true and the t built-in condition false. This can be reversed using 
the troff request. 

Open f i 1 ena me for writing and associate the stream named stream with it. See also the close and 
write requests. 



.openas t r eamf i I ena 
.pnr 

.psocommand 

.ptr 

.rcharc lc2 ... 

.rj, .rjn 

.rnnxxyy 
.shcc 


.shiftn 

.specialsls2... 
.stynf 


.tkff slnls2n2 


.trff i I ena me 


.trnt abed 
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Like open, but if f i i ename exists, append to it instead of truncating it. 

Print the names and contents of all currently defined number registers on stderr. 

This behaves like the so request except that input comes from the standard output of command. 

Print the names and positions of all traps (not including input line traps and diversion traps) on 
stderr. Empty slots in the page trap list are printed as well, because they can affect the priority of 
subsequently planted traps. 

Remove the definitions of characters c 1 , c2 , ... This undoes the effect of a char request. 

Right justify the next n input lines. Without an argument, right justify the next input line. The 
number of lines to be right justified is available in the \n[.rj] register. This implicitly does .ceo. 
Thece request implicitly does. rjo. 

Rename number register** toyy. 

Set the soft hyphen character to c. If c is omitted, the soft hyphen character will beset to the 
default \ <hy. T he soft hyphen character is the character that will be inserted when a word is 
hyphenated at a I ine break. I f the soft hyphen character does not exist in the font of the character 
immediately preceding a potential break point, then the I ine will not be broken at that point. 

N either definitions (specified with the chan request) nor translations (specified with them request) 
are considered when finding the soft hyphen character. 

In a macro, shift the arguments by n positions: argument i becomes argument i -n; arguments i to n 
will no longer be available. If n is missing, arguments will be shifted by i. Shifting by negative 
amounts is currently undefined. 

Fonts s 1, s 2 are special and will be searched for characters not in the current font. 

Associate style f with font position n. A font position can be associated either with afontorwith a 
style. The current font is the index of a font position and so is also either a font or a style. When it 
is a style, thefontthat is actually used is the font the name of which is the concatenation of the 
name of the current family and the name of the current style. For example if the current font is i 
and font position i is associated with style r and the current font family isT, then font tr will be 
used. If the current font is not a style, then the current family is ignored. When the requests cs, bd, 
tkt, uf, or f special are applied to a style, then they will instead be applied to the member of the 
current family correspondi ng to that style. T he default family can be set with the -f option. T he 
styles command in theDEsc file controls which font positions (if any) are initially associated with 
styles rather than fonts. 

Enable track kerning for font f. When the current font isf, the width of every character will be 
increased by an amount between ni and n2; when the current point size is less than or equal to si, 
thewidth will beincreased bym; when it is greater than or equal to s 2 , the width will beincreased 
by n 2 ; when the point size is greater than or equal to si and less than or equal to s 2, theincreasein 
width is a linear function of the point size. 

T ransparently output the contents of filet i i ename. Each line is output as it would be were it 
preceded by \i; however, the lines are not subject to copy-mode interpretation. If the file does not 
end with a newline, then a newline will be added. For example, you can define a macro * 
containi ng the contents of fi le f, usi ng 

.dix 

.trff 

.di 

Unlike with theef request, the file cannot contain characters such as nul that are not legal trott 
input characters. 

T his is the same as the tr request except that the translations do not apply to text that is transpar¬ 
ently throughput into a diversion with \i. For example, 

.tr ab 
.di x 
\!.tm a 
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.troff 

. vptn 

.warnn 

.whilecanyt hi ng 

.writest reamanyt hi ng 

EXTENDED REQUESTS 

.cff i I ename 

.evxx 

.fpnflf 2 

.ssmn 


.tan In2.. .nnTr 1 r2... 


.di 

.x 

will print b; if trnt is used instead of tr, it will print a. 

M akethen built-in condition false, and the t built-in condition true. Thisundoestheeffect of the 
nroft request. 

Enable vertical position traps if n isnonzero, disable them otherwise. Vertical position traps are 
traps set by thewh or dt requests. T raps set by the it request are not vertical position traps. T he 
parameter that controls whether vertical position traps are enabled is global. Initially, vertical 
position traps are enabled. 

Control warnings, n isthesum of the numbers associated with each warningthat isto be enabled; 
all other warnings will be disabled. The number associated with each warning is listed in the 
"Warnings" subsection. For example .warn 0 will disable all warnings, and .warn 1 will disable all 
warnings except that about missing characters. If n isnot given, all warnings will be enabled. 

W hile condition c is true, accept a nyt hi ng as input; c can beany condition acceptable to an it 
request; anythi ng can comprise multiple lines if thefirst line starts with \{ and the last lineends 
with \}. See also thebreak and continue requests. 

Write a nyt hi ng to the stream named stream, stream must previously have been the subject of an 
open request, anythi ng is read in copy mode; a leading will be stripped. 


When used in a diversion, thiswill embed in thediversion an object which, when reread, will cause 
the contents off i 1 ename to be transparently copied through to the output. In UN IX troff, the 
contents of t i 1 ena me are immediately copied through to the output regardless of whether there is a 
current diversion; this behavior is so anomalous that it must be considered a bug. 

If ** isnot a number, thiswill switch to a named environment called xx. The environment should 
be popped with a matching ev request without any arguments, just as for numbered environments 
There is no limit on the number of named environments; they will be created thefirst time that 
they are referenced. 

Thefp request has an optional third argument. This argument gives the external name of the font, 
which is used for finding the font description file. The second argument gives the internal name of 
the font, which is used to refer to the font in troff after it has been mounted. If there is no third 
argument, then the internal name will be used as the external name. This feature allows you to use 
fonts with long names in compatibility mode. 

When two arguments are given to thess request, the second argument gives the sentence space size. 
If the second argument isnot given, the sentence space size will be the same as the word space size. 
Liketheword spacesize, the sentence space is in unitsof one twelfth of thespacewidth parameter 
for the current font. Initially, both the word space size and the sentence space size are 12 . The 
sentence space size is used in two circumstances: If the end of a sentence occurs at the end of aline 
in fill mode then both an interword space and a sentence space will be added; if two spaces follow 
the end of a sentence in the middle of a line, then the second space will be a sentence space. N ote 
that the behavior of U N IX troff will be exactly that exhibited by GN U troff if a second argument 
is never given to thess request. In GN U troff, as in U NIX troff, you should always follow a 
sentence with either a newline or two spaces. 

Set tabs at positions n 1 , n 2 ,...,nn and then set tabs at n n +r 1 , n n +r 2 ,. . .., nn+rn and then at 
nn+r n+r i, nn +r n +r 2,..., nn+r n+r n, and so on. For example, .ta t , 5 i will set tabs every half an 
inch. 



\n[.fan] 
\n[.fp] 

\n[.0] 

\n[.hla] 
\n[.hlc] 
\n[.him] 
\n[-hy] 

\n[.hym] 
\n[.hys] 
\n[.in] 

\n[.kern] 
\n[-lg] 

\n[.11] 

\ n [. It ] 

\n[.ne] 

\n[.pn] 

\n[.ps] 

\n[.psr] 
\n[.rj] 

\n[.sr] 

\n[.tabs] 
\n[.trunc] 


\n[.ss] 
\n[.sss] 
\n[.vpt] 
\n[.warn] 

\n(.x 

\n(.y 
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Thecurrent font family. This is a string-valued register. 

T he number of the next free font position. 

Alwaysi. M acros should usethisto determine whether they are running under GNU troft. 

Thecurrent hyphenation language as set by thema request. 

The number of immediately preceding consecutive hyphenated lines. 

The maximum allowed number of consecutive hyphenated lines, asset by the him request. 

Thecurrent hyphenation flags (asset by the ny request.) 

Thecurrent hyphenation margin (as set by the hym request.) 

Thecurrent hyphenation space (as set by the hys request.) 

T he indent that applies to the current output line. 
i if pairwise kerning is enabled, 0 otherwise. 

Thecurrent ligature mode (as set by the ig request.) 

The line length that applies to thecurrent output line. 

The title length as set by the it request. 

Theamountof space that was needed in the last ne request that caused atrap to be sprung. Useful in 
conjunction with the \n[ .trunc] register. 

T he number of the next page either the value set by a pn request, or the number of the current page 
plus 1. 

Thecurrent pointsizein scaled points 

The last requested pointsizein scaled points 

The number of lines to be right-justified asset by the nj request. 

The last requested pointsizein points as a decimal fraction. This is a string-valued register. 

A string representation of thecurrent tab settings suitable for use as an argument to theta request. 
Theamountof vertical space truncated by the most recently sprung vertical position trap, or, if the trap 
was sprung by an ne request, minus the amount of vertical motion produced by thene request. In other 
words, at the point a trap is sprung, it represents the difference of what the vertical position would have 
been but for the trap, and what the vertical position actually is Useful in conjunction with the\n[. ne] 
register. 

These give the values of the parameters set by the first and second arguments of the ss request. 

1 if vertical position traps are enabled, 0 otherwise. 

Thesum of the numbers associated with each of the currently enabled warnings. The number associated 
with each warning is listed in the"W arnings" subsection. 

The major version number. For example, iftheversion number is 1.03 then \n(.x will contain 1 . 

The minor version number. For example, iftheversion number is 1.03 then \n(.y will contain 03. 
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T he foil owing registers are set by the \w escape sequence: 

\n[rst] 

\n[ rsb] Like the st and sb registers, but takes account of the heights and depths of characters. 

\n[ssc] The amount of horizontal space (possibly negative) that should be added to the last character before a 

subscript. 

\n [ skw] H owfar to right of the center of the last character in they# argument, the center of an accent from a 

roman font should be placed over that character. 

Thefollowing read/write number registers are available: 

\n[systat] The return value of the system) ) function executed by the last sy request. 

\n[siimit ] If greater than 0, the maximum number of objects on the input stack. If less than or equal to 0, there is no 

limit on the number of objects on the input stack. W ith no limit, recursion can continue until virtual 
memory is exhausted. 

MISCELLANEOUS 

Fonts not listed in theDEsc file are automatically mounted on the next avail able font position when they are referenced. 

If a font is to be mounted explicitly with the f p request on an unused font position, it should be mounted on the first unused 
font position, which can be found in the \n[ .tp] register; although troff does not enforce this strictly, it will notallow a font 
to be mounted at a position whose number is much greater than that of any currently used position. 

Interpolating a string does not hide existing macro arguments. Thus in a macro, a more efficient way of doing 

■XX\\$@ 

is 

\\*[XX]\\ 

If the font description file contains pairwise kerning information, characters from that font will be kerned. Kerning between 
two characters can be inhibited by placing a \& between them. 

In a string comparison in a condition, characters that appear at different input levels to the first delimiter character will not 
be recognized asthesecond or third delimiters. Thisapplies also to then request. In a \w escape sequence, a character that 
appears at a different input level to the starting delimiter character will not be recognized as the closing delimiter character. 
When decoding a macro argument that is delimited by double quotes, a character that appears at a different input level to 
the starting delimiter character will not be recognized as the closing delimiter character. The implementation of \$@ ensures 
that the double quotes surrounding an argument will appear the same input level, which will be different to the input level 
of the argument itself. In a long escape name] will not be recognized asaclosing delimiter except when it occurs at the same 
input level asthe opening ]. In compatibility mode, no attention is paid to the input level. 

T here are some new types of condition: 

.ifrxxx True if there is a number register named xxx. 

. ifdxxx T rue if there is a string, macro, diversion, or request named xxx. 

. if cc h T rueif there is a character ch available; ch is either an ASCII character or a special character \<xx or \[xxx]; the 

condition will also be true if ch has been defined by the char request. 


WARNINGS 

The warnings that can be given by troff are divided into thefollowing categories. The name associated with each warning is 
used by the -w and -w options; the number is used by thewarn request, and by the .warn register. 

chari N onexistent characters. T his is enabled by default. 

number2 Invalid numeric expressions. T his isenabled by default. 

break4 In fill mode, lines which could not be broken so that their length was less than the line length. This is 

enabled by default. 

M issing or mismatched closing delimiters. 


delim8 
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eii6 Useof theei request with no matching ie request. 

scaie32 M eaningless scaling indicators. 

range64 0 ut of range arguments 

syntaxes D ubious syntax in numeric expressions. 

di256 Useof di or da without an argument when there isno current diversion. 

mac5i2 Useof undefined strings, macros, and diversions When an undefined string, macro, or diversion is used, 

that string is automatically defined as empty. So, in most cases, at most one warning will be given for each 
name. 


reg1024 

tab2048 

right-brace4096 
missing8192 
input16384 
escape32768 

space65536 


font131072 

ig262144 


Useof undefined number registers. When an undefined number register is used, that register ^automati¬ 
cally defined to have a value of 0 . A definition is automatically made with a value of 0 . So, in most cases, at 
most one warning will be given for use of a particular name. 

I nappropriate use of a tab character. E ither use of a tab character where a number was expected, or use of 
tab character in an unquoted macro argument. 

U se of \g where a number was expected. 

Requests that are missing nonoptional arguments. 

Illegal input characters. 

U nrecognized escape sequences. W hen an unrecognized escape sequence is encountered, the escape 
character is ignored. 

M issing space between a request or macro and its argument. Thiswarningwill be given when an 
undefined name longer than two characters is encountered, and the first two characters of the name make 
a defined name. The request or macro will not be invoked. When thiswarning isgiven, no macro is 
automatically defined. This is enabled by default. Thiswarningwill never occur in compatibility mode. 

N onexistent fonts This is enabled by default. 

Illegal escapes i n text ignored with theig request. These are conditions that are errors when they do not 
occur in ignored text. 


There are also names that can be used to refer to groups of warnings: 

an All warnings except di, mac, and reg. Itisintended that this covers all warnings that are useful with 

traditional macro packages, 
w All warnings. 


INCOMPATIBILITIES 

Long names cause some incompatibilities. UNIX troff will interpret 
.dsabcd 

as defining a string ab with contents cd. Normally, GNU troff will interpret thisasacall of amacro named dsabcd. Also 
UNIX troff will interpret \*[ or \n[ as references to a string or number register called [. In GNU troff, however, this will 
normally be interpreted as the start of a long name. In compatibility modeGN U troff will interpret these things in the 
traditional way. In compatibility mode, howa/er, long names are not recognized. Compatibility mode can be turned on with 
the-c command-line option, and turned on or off with thecp request. The number register \n(.c is 1 if compatibility mode 
is on, 0 otherwise. 

GNU troff does not allow the use of the escape sequences in names of strings, macros, diversions, number registers, fonts, or 
environments; U N IX troff does. The \a escape sequence may be helpful in avoiding use of these escape sequences in names. 

Fractional point sizes cause one noteworthy incompatibility. In U NIX troff theps request ignores scale indicators and so 

.ps 10U 

will set the pointsize to 10 points, whereas in GN U troff it will set the pointsize to 10 scaled points 
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In GNU troff there is a fundamental difference between unformatted, input characters, and formatted, output characters. 

E verythi ng that affects how an output character will be output is stored with the character; after an output character has been 
constructed, it is unaffected by any subsequent requests that are executed, including bd, cs, tkf, tr, ortp requests. Normally 
output characters are constructed from input characters at the moment immediately before the character is added to the 
current output line. M acros, diversions, and strings are all, in fact, the same type of object; they contain lists of input 
characters and output characters in any combination. An output character does not behave like an input character for the 
purposes of macro processing; it does not inherit any of the special properties that the input character from which it was 
constructed might have had. For example this: 

.di x 
\\\\ 

.br 

.di 

.x 

will print \\ in GN U troff; each pair of input \sisturned into one output \ and the resulting output \s are not interpreted 
as escape characters when they are reread. U N IX troff would interpret them as escape characters when they were reread and 
would end up printing one \ . The correct way to obtain a printable \ is to use the \e escape sequence: this will always print a 
single instance of the current escape character, regardless of whether or not it is used in adiversion; itwill also work in both 
GNU troff and U N IX troff. If you wish for some reason to store in a diversion an escape sequence that will be interpreted 
when thediversion is reread, you can either use the traditional \i transparent output facility, or, if this is unsuitable, thenew 
\? escape sequence. 

ENVIRONMENT 

GROFF_TMAC_PATH 
GROFF_TYPESETTER 
GROFF FONT PATH 


A co I on-separated list of directories in which to search for macro files. 

D efault device. 

A co I on-separated list of directories in which to search forthedevname directory, troff will search 
in directories given in the -f option before these, and in standard directories (:/usr/iib/groff/font, 
: /usr/nb/f ont, and : /usr/iib/font) after these. 


FILES 

/usr/lib/groff/font/devname/DESC 
/usr/lib/groff/tmac/troffrc 
/usr/lib/groff/tmac/tmac.name 
/usr/lib/groff/font/devname/DESC 
/usr/lib/groff/font/devname/F 


Initialization file 
M aero files 

Devicedescription file for device name 
Font file for font F of devicename 


SEE ALSO 

groff(l) gtbl(l), gpic(l), geqn(l), grops(l), grodvi(l), grotty(l), groff_font(5), groff_out(5), groff_char(7) 

Groff Verson 1.09,14 February 1994 


gzip, gunzip, zcatgzip, gunzip, zcat 

gzip, gunzip, zcatgzip, gunzip, zcat— C ompress Of expand files 

SYNOPSIS 


gzip [ -acdfhlLnNrtvV19 ][-Ssuffix] [ name ... ] 
gunzip [ -acfhlLnNrtvV ][-Ssuffix] [ name ... ] 
zcat [ -fhLV ] [name ... ] 
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DESCRIPTION 

gzip reduces the size of the named files using Lempel-Ziv coding ( 1111 ). W henever possible, each file is replaced by one 
with the extension .gz, while keeping the same ownership modes, access, and modification times. (The default extension is 
-gz for VM S, z for M S-DOS, OS/2 FAT, Windows NT FAT and Atari.) If no files are specified, or if a filename is-, the 
standard input is compressed to the standard output, gzip will only attempt to compress regular files. In particular, it will 
ignore symbolic links. 

If the compressed filename is too long for its filesystem, gzip truncates it. gzip attempts to truncate only the parts of the 
filename longer than three characters. (A part is delimited by dots.) If the name consists of small parts only, the longest parts 
are truncated. For example, if filenames are limited to 14 characters, gzip.msdos.exe is compressed to gzi.msd.exe.gz. N ames 
are not truncated on systemsthat do not have a limit on filename length. 

By default, gzip keeps the original filename and timestamp in the compressed file. These are used when decompressing the 
file with the-N option. This is useful when the compressed filename was truncated or when the time stamp was not preserved 
after a fi le transfer. 

Compressed files can be restored to their original form using gzip -d or gunzip or zcat. If the original name saved in the 
compressed file is not suitable for itsfilesystem, a new name is constructed from the original one to make it legal. 

gunzip takes a list of files on its command line and replaces each file whose name ends with .gz, -gz, .z, -z, z, or .z and which 
begins with the correct magic number with an uncompressed file without the original extension, gunzip also recognizes the 
special extensions .tgz and .taz as shorthands for .tar.gz and .tar.z respectively. W hen compressing, gzip uses the .tgz 
extension if necessary instead of truncating a file with a .tar extension. 

gunzip can currently decompress files created by gzip, zip, compress, compress -h, or pack. The detection ofthe input format 
is automatic. When using the first two formats, gunzip checks a 32-bit C RC. For pack, gunzip checks the uncompressed 
length. The standard compress format was not designed to allow consistency checks. FI owa/er, gunzip is sometimes able to 
detect a bad .z file If you get an error when uncompressing a .z file do not assume that the .z file is correct simply because 
the standard uncompress does not complain. This generally means that the standard uncompress does not check its input, and 
happily generates garbage output. The SCO compress -h format (izh compression method) does not include a CRC but also 
allows some consistency checks. 

Files created by zip can be uncompressed by gzip only if they have a single member compressed with the deflation method. 
This feature is only intended to help conversion of tar. zip files to the tar.gz format. T o extract zip files with several 
members, use unzip instead of gunzip. 

zcat is identical to gunzip -c. (On some systems, zcat may deinstalled asgzcat to preserve the original link to compress.) 
zcat uncompresses either a list of fi les on the command line or its standard input and writes the uncompressed data on 
standard output, zcat will uncompress files that have the correct magic number whether they havea .gz suffixornot. 

gzip uses the Lempel-Ziv algorithm used in zip and pkzip. The amount of compression obtained depends on the size of the 
input and the distribution of common substrings. Typically, text such as source code or English is reduced by 60 to 70 
percent. Compression is generally much better than that achieved by LZW (as used in compress), H uffman coding (as used 
in pack), or adaptive FI uffman coding (compact). 

Compression is always performed, even if the compressed file is slightly larger than the original. The worst case expansion is a 
few bytes for the gzip file header, plus 5 bytes every 32 KB block, or an expansion ratio of 0.015 percent for large files. N ote 
thattheactual number of used disk blocks almost never increases, gzip preserves the mode, ownership, and timestampsof 
files when compressing or decompressing. 

OPTIONS 

-a -ascii ASCII textmode convert end-of-lines using local conventions. Thisoption is supported 

only on some non-U NIX systems. For M S-DOS, cr lf is converted to lf when compress¬ 
ing, and lf is converted to cr LFwhen decompressing. 

-c -stdout -to-stdout Write output on standard output; keep original files unchanged. If there are several input 

files, the output consists of a sequence of independently compressed members. T o obtain 
better compression, concatenate all input files before compressing them. 
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-d -decompress -uncompress 
-f -force 


-h -help 
-1 -list 


-L -license 
-n -no-name 


-N -name 


-q -quiet 
-r -recursive 


-S .suf -suffix .suf 


-t -test 
-v -verbose 

-V -version 
-# -fast -best 


D ecompress. 

Force compression or decompression even if the fi le has multiple links or the correspond! ng 
file already exists, or if the compressed data is read from or written to a terminal. If the 
input data is not in a format recognized by gzip, and if the option -stdout is also given, 
copy the input data without change to the standard output; let zcat behave as cat. If f is 
not given, and when not running in the background, gzip prompts to verify whether an 
existing file should be overwritten. 

D isplay a help screen and quit. 

For each compressed file, list the following fields: compressed size (size of the compressed 
file), uncompressed size (size of the uncompressed file), ratio (compression ratio—0.0% if 
unknown), uncompressed name(nameof the uncompressed file). The uncompressed size is 
given as -i for files not in gzip format, such as compressed .z files. To get the uncompressed 
size for such a file, you can use: 
zcat file.Z j wc -c 

In combination with the -verbose option, the following fields are also displayed: method 
(compression method), crc (the 32-bit CRC of the uncompressed data), date & time 
(timestamp for the uncompressed file). The compression methods currently supported are 
deflate, compress, lzh (SC 0 compress -h) and pack. T he crc is given 3S ffffffff for a file 
not in gzip format. 

With -name, the uncompressed name date and time are those stored within the compressed 
file if present. 

With -verbose, the size totals and compression ratio for all files is also displayed, unless 
some sizes are unknown. W ith -quiet, the title and totals lines are not displayed. 

D isplay the gzip license and quit. 

When compressing, do not save the original filename and timestamp by default. (The 
original name is always saved if the name had to be truncated.) W hen decompressing, do 
not restore the origi nal filename if present (remove only the gzip suffix from the compressed 
filename) and do not restore the origi nal timestamp if present (copy it from the compressed 
file). Thisoption isthedefault when decompressing. 

When compressing, always save the origi nal filenameand timestamp; this is the default. 
When decompressing, restore the origi nal filenameand timestamp if present. Thisoption is 
useful on systems that have a limit on filename length or when the timestamp has been lost 
after a fi le transfer. 

Suppress all warnings. 

T ravel the directory structure recursively. If any of the filenames specified on the command 
line are directories, gzip will descend into the directory and compress all the files it finds 
there (or decompress them in thecaseof gunzip). 

Use suffix .suf instead of .gz. Any suffix can be given, but suffixes other than .z and .gz 
should be avoided to avoid confusion when files are transferred to other systems. A null 
suffix forces gunzip to try decompression on all given files regardless of suffix, as in the 
following: 

gunzip -S "" * (*.* for M S-D 0 S) 

Previous versions of gzip used the .z suffix. This was changed to avoid a conflict with 

pack(l). 

T est. Check the compressed file integrity. 

Verbose. D isplay the nameand percentage reduction for each file compressed or decom¬ 
pressed. 

Version. D isplay the version number and compilation options, then quit. 

Regulate the speed of compression using the specified digit#, where-i or --fast indicates 
thefastest compression method (less compression) and -9 or - best indicatestheslowest 
compression method (best compression). The default compression level is -6 (that is, biased 
towards high compression at expense of speed). 
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ADVANCED USAGE 

M ultiple compressed files can be concatenated. In this case, gunzip will extract all members at once For example, 

gzip -c filel >foo.gz gzip -c file2»> foo.gz 

Then 

gunzip -c foo 

is equivalent to 

cat filel file2 

In case of damage to one member of a .gz file, other members can still be recovered (if the damaged member is removed). 

H owever, you can get better compression by compressing all members at once. 

cat filel file2 j gzip > foo.gz 

compresses better than 

gzip -c filel file2 >foo.gz 

If you want to recompress concatenated files to get better compression, use 

gzip -cd old.gz ] gzip > new.gz 

If a compressed file consists of sa/eral members, the uncompressed sizeandCRC reported bythe-iist option applies to the 
last member only. If you need the uncompressed size for all members, you can use 

gzip -cd file.gz j wc -c 

If you wish to create a single archive file with multiple members so that members can later be extracted independently, use an 
archiver such as tar or zip. GNU tar supports the -z option to invoke gzip transparently, gzip is designed as a complement 
to tar, not as a replacement. 

ENVIRONMENT 

T he environment variable gzip can hold a set of default options for gzip. T hese options are interpreted first and can be 
overwritten by explicit command-line parameters. For example 

For sh: GZIP="-8v -name" 

Export GZIP for csh: setenv GZIP "-8v -name" 

For MS-DOS: set GZIP=-8v -name 

On Vax/VM S, the name of the environment variable is gzip_opt, to avoid a conflict with the symbol set for invocation of the 
program. 

SEE ALSO 

znew(l), zcmp(l), zmore(l), zforce(l), gzexe(l), zip(l), unzip(l), compress(l), pack(l), compact(l) 

DIAGNOSTICS 

Exit status is normally 0; if an error occurs, exit status isl. If a warning occurs, exit status is 2. 

USage gzip [-cdfhlLnNrtvV19] [-S suffix] [file ...] 

Invalid options were specified on thecommand line, 
file: not in gzip format 

The file specified to gunzip has not been compressed, 
file: Corrupt input. Use zcat to recover some data. 

T he compressed file has been damaged. T he data up to the point of failure can be recovered usi ng 


zcat file > recover 
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file: compressed with xx bits, can only handle yy bits 

file was compressed (using LZW) by a program that could deal with more bits than the decompress code on this machine. 
Recompress thefile with gzip, which compresses better and uses less memory, 
file: already has .gz suffix--no change 

The file is assumed to be already compressed. Rename the file and try again, 
file already exists; do you wish to overwrite (y or n)? 

Respond y if you want the output file to be replaced; n if not. 
gunzip: corrupt input 

A SIGSEGV violation was detected, which usually meansthat the input file has been corrupted. 

XX. x% 

Percentage of the input saved by compression. (Relevant only for-v and -I.) 

- not a regular file or directory: ignored 

When the input file is not a regular file or directory, (such as a symbolic link, socket, FIFO, device file), it is left unaltered. 

- has xx other links: unchanged 

The input file has I inks; it is left unchanged. Seeln(l) for more information. 

U se the -f flag to force compression of files that are multiply linked. 

CAVEATS 

When writing compressed data to a tape it is generally necessary to pad the output with zeroes up to a block boundary. 
When the data is read and the whole block is passed to gunzip for decompression, gunzip detects that there is extra trailing 
garbage after the compressed data and emitsawarning by default. You have to use the -quiet option to suppress the 
warning. Thisoption can beset in theGzip environmentvariableasin thefollowing: 

for sh: GZIP="-q" tar -xfz -block-compress /dev/rst@ for csh: 

(setenv GZIP -q; tar -xfz -block-compr /dev/rst0 

In the preceding example, gzip is invoked implicitly by the -z option of GN U tan. M ake sure that the same block size ( -b 
option of tar) is used for reading and writing compressed data on tapes. (This example assumes you are using theGN U 
version of tar.) 

BUGS 

The -list option reports incorrect sizes if they exceed two gigabytes. The -list option reports sizes as -i and crc astfffftff 
if the compressed fi le is on a nonseekable media. 

In some rare cases, the -best option gives worse compression than the default compression level (-6). On some highly 
redundant files, compress compresses better than gzip. 

Local 


gzexe 

gzexe— Compress executable files in place 

SYNOPSIS 


gzexe [ name ... ] 



head 



DESCRIPTION 

Thegzexe utility enables you to compress executables in place and have them automatically uncompress and execute when 
you run them (at a penalty in performance). For example if you execute gzexe /bin/oat, it will create the foil owing two files: 

-r-xr-xr-x 1 root bin 9644 Feb 11 11:16 /bin/cat 
-r-xr-xr-x 1 bin bin 24576 Nov 23 13:21 /bin/cat' 

/bin/cat" is the ori gi nal fileand /bin/cat is the self-uncompressing executable file You can remove /bin/cat" when you are 
sure that /bin/cat works properly. 

This utility is most useful on systems with very small disks. 

OPTIONS 

-d Decompress the given executables instead of compressing them 

SEE ALSO 

gzip(l), znew(l), zmore(l), zcmp(l), zforce(l) 

CAVEATS 

Thecompressed executable is a shell script. This may create some security holes. In particular, thecompressed executable 
relies on the path environment variable to find gzip and some other utilities (tail, chmod, in, sleep). 

BUGS 

gzexe attempts to retain the original file attributes on thecompressed executable but you may have to fix them manually in 
some cases, using chmod or chown. 

head 

head— 0 utput the first part of files 

SYNOPSIS 

head [-c N[bkm]] [-n N] [-qv] [--bytes=N[bkm]] [--lines=N] [--quiet] [--silent] 

[--verbose] [--help] [--version] [file...] 

head [-Nbcklmqv] [file...] 

DESCRIPTION 

This manual page documents the GN U version of head, head prints the first part (10 lines by default) of each given file it 
reads from standard input if no files are given or when a filename of - is encountered. If more than one file is given, it prints 
a header consisting of the file's name enclosed in ==> and <== before the output for each file 

OPTIONS 

head accepts two option formats: the new one in which numbers are arguments to the option letters; and theold one in 
which the number precedes any option letters. 

-c n, --bytes n Print first n bytes n isanonzero integer, optionally followed by one of the following characters to 

specify a different unit, 
b 512-byte blocks, 
k 1-kilobyte blocks, 
m 1-megabyte blocks 
-l, -n n, - -lines n Print first n lines. 

-g, - -quiet, - -silent N ever print filename headers. 
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-v, - -verbose 
--help 
--version 


Always print filename headers. 

Print a usage message and exit with a nonzero status. 
Print version information on standard output, then exit. 


GNU Text Utilities 


hexdump 

hexdump— ASCII, decimal, hexadecimal, octal dump 

SYNOPSIS 

hexdump [-bcdovx] [-e format_string] [-f format_file] [-n length] [-s skip] [file ...] 


DESCRIPTION 

T he hexdump utility is a fi Iter that displays the specified files, orthestandard input, if no files are specified, in a user-specified 
format. 


The options are as follows: 


-e format_string 
-f format_file 


-n length 
-o 

-s offset 


One-byte octal display. D i splay the input offset in hexadecimal, followed by sixteen space- 
separated, three-column, zero-filled bytesof input data, in octal, per line. 

One-byte character display. D isplay the input offset in hexadecimal, followed by sixteen space- 
separated, three-column, space-filled, characters of input data per line. 

Two-byte decimal display. Display the input offset in hexadecimal, followed by eight space- 
separated, five-column, zero-filled, two-byte units of input data, in unsigned decimal, per line. 
Specify a format string to be used for displaying data. 

Specify a file that contains one or more newline separated format strings. Empty lines and lines 
whose first nonblank character is a hash mark (#) areignored. 

Interpret only length bytes of input. 

T wo-byte octal display. D isplay the input offset in hexadecimal, followed by eight space-separated, 
six-column, zero-filled, two-byte quantities of input data, in octal, per line 
Skipotfset bytes from the beginning of the input. By default, offset is i nterpreted asadecimal 
number. W ith a leading ox or ox, offset is interpreted as a hexadecimal number; otherwise, with a 
leading 0 , offset is interpreted as an octal number. Appending the character t>, k, or m to offset 
causes it to be interpreted as a multiple of 512,1024, or 1048576, respectively. 

The -v option causes hexdump to display all input data. Without the -v option, any number of 
groups of output lines, which would be identical to the immediately preceding group of output 
lines (except for the input offsets), are replaced with a line comprised of a single asterisk. 

T wo-byte hexadecimal display. D isplay the input offset in hexadecimal, followed by eight, space- 
separated, four-column, zero-filled, two-byte quantities of input data, in hexadecimal, per line. 


For each input file hexdump sequentially copies the input to standard output, transforming the data accordingto theformat 
strings specified by the -e and -f options, in theorder that they were specified. 

FORMATS 

A format string contains any number of format units, separated by whitespace. A format unit contains up to three items: an 
iteration count, a byte count, and a format. 

T he iteration count isan optional positive integer, which defaults to one. Each format isapplied iteration counttimes. 

The byte count is an optional positive integer. If specified, it defines the number of bytes to be interpreted by each iteration 
of theformat. 



hexdump 


If an iteration count and/or a byte count is specified, a single slash must be placed after the iteration count and/or before the 
byte count to disambiguate them. Any whitespace before or after the slash is ignored. 

The format is required and must be surrounded by double quote ("") marks. It is interpreted as an fprintf -style format 
string (see fprintt (3)) with thefollowing exceptions: 

■ An asterisk (*) may not beused asafield width or precision. 

■ A byte count or field precision is required for each s conversion character (uni ike the fprintf (3) default, which prints 
theenti re string if the precision isunspecified). 

■ The conversion characters h, 1 , n, p, and q are not supported. 

■ Thesingle-characterescapesequencesdescribed intheC standard are supported: 


NUL 

\0 

Alert character 

\a 

Backspace 

\b 

Form-feed 

\f 

N ewline 

\n 

Carriage return 

\r 

T ab 

\t 

Vertical tab 

\v 


hexdump also supports the following additional conversion strings: 

a[dox] D isplay the input offset, cumulative across input files, of the next byte to be displayed. The appended characters 
d, o, and x specify the display base as decimal, octal, or hexadecimal respectively. 
a[ dox ] Identical to the a conversion string except that it is only performed once, when all of the input data has been 
processed. 

c Output characters in the default character set. N onprinting characters are displayed in three-character, zero- 

padded octal, except for those representable by standard escape notation (see preceding list), which are displayed 
as two-character strings. 

p 0 utput characters in the default character set. N onprinting characters are displayed as a single period, 

u 0 utput U .S. ASC11 characters, with the exception that control characters are displayed using the lowercase names 

in thefollowing mini-table. C haracters greater than 0 xff, hexadecimal, are displayed as hexadecimal strings. 


000 nul 

001 soh 

002 stx 

003 etx 

004 eot 

005 enq 

006 ack 

007 bel 

008 bs 

009 ht 

00A If 

00B vt 

00C ff 

00D cr 

00E SO 

00F si 

010 die 

011 del 

012 dc2 

013 dc3 

014 dc4 

015 nak 

016 syn 

017 etb 

018 can 

019 em 

01 A sub 

01 B esc 

01C fs 

01 D gs 

01 E rs 

01 F us 

OFF del 





T he default and supported byte counts for the conversion characters are as follows: 

%_c, %_p, %_u, %c 0 ne-byte counts only. 

%d, %i, %o, %u, %x, %x Four-byte default; one-, two-, and four-byte counts supported. 

%e, %e, %f, %g, %g Eight-byte default, four-byte counts supported. 

The amount of data interpreted by each format string is the sum of the data required by each format unit, which is the 
iteration count times the byte count, or the iteration count times the number of bytes required by the format if the byte 
count is not specified. 

The input is manipulated in blocks, a block is defined as the largest amount of data specified by any format string. Format 
strings interpreting less than an input block's worth of data, whose last format unit both interprets some number of bytes 
and does not have a specified iteration count, have the iteration count incremented until the entire input block has been 
processed or there is not enough data remaining in the block to satisfy theformat string. 
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If, either as a result of user specification or hexdump modifying the iteration count as described, an iteration count is greater 
than one, no trailing whitespace characters are output during the last iteration. 

It is an error to specify a byte count as well as multiple conversion characters or strings unless all but one of the conversion 
characters or strings is a or a. If, as a result of the specification of the -n option or end-of-file being reached, input data only 
partially satisfies a format string, the input block is zero-padded sufficiently to display all available data (that is, any format 
units overl apping the end of data will display somenumber of thezero bytes). 

Further output by such format strings isreplaced by an equivalent number of spaces. An equivalent number of spaces is 
defined asthenumber of spaces output by an s conversion character with thesamefield width and precision astheoriginal 
conversion character or conversion string but with any+, “", # conversion flag characters removed, and referencing a null 
string. 

If no format strings are specified, the default display is equivalent to specifying the -x option, 
hexdump exits 0 on success and >0 if an error occurred. 

EXAMPLES 

Display the input in perusal format: 

"%06.6_ao " 12/1 "%3_u 11 

,\ t \ t . " % _ p - 
"\rr 

Implement the -x option: 

"%07.7_Ax\n“ 

"%07.7_ax " 8/2 "%04x " "\n" 


SEE ALSO 

adb(l) 


18 April 1994 


hipstopgm 

hipstopgm— C onvert a H IPS file into a portable gray map 

SYNOPSIS 

hipstopgm [hipsfile] 

DESCRIPTION 

Hipstopgm reads a H IPS file as input and produces a portable graymap as output. 

If the H IPSfile contains more than oneframein sequence hipstopgm will concatenate all theframes vertically. 
HIPS is a format developed at the Human Information Processing Laboratory, NYU. 

SEE ALSO 

pgm(5) 

AUTHOR 

Copyright© 1989 byjef Poskanzer 


24 August 1989 
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host 

host— Look up hostnames using domain server 

SYNOPSIS 

host [-1] [-v] [-w] [-r] [-d] [-t querytype] [-a] host [ server ] 

DESCRIPTION 

host looks for information about Internet hosts. It gets this information from a set of interconnected servers that are spread 
across the country. By default, it simply converts between hostnames and Internet addresses. H owever with the -t or -a 
options, it can be used to find all of the information about this host that is maintained by the domain server. 

The arguments can be either hostnames or host numbers. The program first attempts to interpret them as host numbers. If 
this fails, it will treat them as hostnames. A host number consists of first decimal numbers separated by dots, for example, 
128.6.4.194. A hostname consists of names separated by dots, for example, topaz, rutgers.edu. U nless the name ends in a 
dot, the local domain is automatically tacked on the end. Thus, a Rutgers user can say "host topaz", and it will actually look 
up topaz.nutgens.edu. If this fails, the name is tried unchanged (in this case, topaz). This same convention is used for mail 
and other network utilities. The actual suffix to tack on the end is obtained by looking at the results of a hostname call, and 
using everything starting at the first dot. (Following isa description of how to customize the hostname lookup.) 

The first argument is the hostname you want to look up. If this is a number, an inverse Query is done; that is, the domain 
system looksin a separate set of databases used to convert numbers to names. 

The second argument is optional. It allows you to specify a particular server to query. If you don't specify this argument, the 
default server (normally the local machine) isused. 

If a name is specified, you may see output of three different kinds. H ere is an example that shows all of them: 

% host sun4 

sun4.rutgers.edu is a nickname for ATHOS.RUTGERS.EDU 
ATHOS.RUTGERS.EDU has address 128.6.5.46 
ATHOS.RUTGERS.EDU has address 128.6.4.4 
ATHOS.RUTGERS.EDU mail is handled by ARAMIS.RUTGERS.EDU 

The user has typed the command host sun4. The first Iineindicatesthatthenamesun4.rutgers.edu is actually a nickname. 
The official hostnameisATHos.RUTGERs.EDu. The next two lines show the address. If a system has more than one network 
interface, there will be a separate address for each. The last lineindicatesthatATHos.RUTGERs.EDu does not receive its own 
mail. M ail for it is taken by aramis.rutgers.edu. There may be more than one such line, as some systems have more than one 
other system that will handle mail for them. T echnically, every system that can receive mail is supposed to have an entry of 
this kind. If the system receives its own mail, there should bean entry the mentions the system itself, for example "XXX mail 
is handled by XXX." H owa/er many systems that receive their own mail do not bother to mention that fact. If a system has a 
"mail is handled by" entry, but no address, this indicates that it is not really part of the Internet, but a system that is on the 
network will forward mail to it. Systems on U senet, bitnet, and a number of other networks have entries of this kind. 

There are a number of optionsthat can beused before the hostname. Most of these options are meaningful only to the staff 
who have to maintain thedomain database. 

The option -w causes host to wait forever for a response. N ormally it will timeout after around a minute. 

Theoption -v causes printout to bein a verbose format.Thisistheofficial domain master file format, which isdocumented 
in the man page for named. Without this option, output still follows this format in general terms, but some attempt is made 
to make it more intelligible to normal users. Without -v, a, mx, and cname records are written out as has address, mail is 
handled by, and is a nickname for, and TT L and class fields are not shown. 

Theoption -r causes recursion to be turned off in the request. This means that the name server will return only data it has in 
its own database. It will notask other servers for more information. 

Theoption -d turnson debugging. N etwork transactions are shown in detail. 
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The option -t allows you to specify a particular type of information to be looked up. The arguments are defined in the man 
page for named. C urrently Supported types are a, ns, md, mf, cname, soa, mb, mg, mr, null, wks, ptr, hinfo, minfo, mx, uinfo, uid, 
gid, unspec, and the wildcard, which may be written as either any or*. T ypesmust be given in lowercase. N ote that the 
default isto look first for a, and then mx, except that if theverboseoption isturned on, the default isonly a. 

T he option -a (for "all") is equivalent to -v -t any. 

T he option -1 causes a listing of a complete domain. For example 
host -1 rutgers.edu 

will give a listing of all hosts in therutgers.edu domain. The -t option is used to filter what information is presented, as you 
would expect. The default is address information, which also include PTR and N S records. The command host: 

-1 -v -t any rutgers.edu 

will give a complete download of the zone data for rutgers.edu, in the official master file format. (H owever the SO A record 
is listed twice for arcane reasons.) 


NOTE 


-i is implemented by doing a complete zone transfer and then filtering out the information you have asked for. This 
command should be used only if it is absolutely necessary. 


CUSTOMIZING HOSTNAME LOOKUP 

In general, if the name supplied by the user does not have any dots in it, a default domain is appended to the end. This 
domain can be defined in /etc/resoiv.cont, but is normally derived by taking the local hostname after its first dot. The user 
can override this, and specify a different default domain, usi ng the environment variable localdomain. In addition, the user 
can supply hisown abbreviations for hostnames. They should bein afileconsistingof oneline per abbreviation. Each line 
contains an abbreviation, aspace, and then the full hostname. T hisfile must be pointed to by an environment variable 
hostaliases, which is the name of the file. 

SEE ALSO 

named(8) 

BUGS 

Unexpected effects can happen when you type a name that is not part of the local domain. Please always keep in mind that 
the local domain name is tacked onto the end of every name unless it ends in a dot. Only if this fails is the name used 
unchanged. 

The -l option only tries the first name server listed for the domain that you have requested. If this server is dead, you may 
need to specify a server manually. For example, to get alistingoffoo.edu, you could try host -t ns foo.edu to get a list of all 
thenameserversforfoo.edu, and then try host -l foo.edu xxx for all xxx on the list of name servers, until you find one that 
works. 

hostid 

hostid— Set or print system's host ID. 

SYNTAX 


hostid [-v] [ deci mal • i d ] 







hostname 



DESCRIPTION 

Thehostid command prints the current host ID number in hexadecimal and both decimal and hexadecimal in parenthesis if 
the-v option is given. This numeric value is expected to be unique across all hosts and is normally set to resemble the host's 
Internet address. 

Only the superuser can set thehostid by giving an argument. This value is stored in the fi le /etc/hostid and need only be 
performed once. 

AUTHOR 

hostid is written by M itch D'Souza (m. dsouza@mrc-apu.cain.ac.uk). 

SEE ALSO 

gethostid(2), sethostid(2) 


hostname 

hostname— Show or set the system's hostname 
dnsdomainname -Show the system's domai n name 

SYNOPSIS 

hostname [-d] [ --domain] [-Ff i I ename ] [ --filef i I ename ] [-f] [ - - fqdn] [-h] [ - - help] 

[--long][-s][--short][-v][--version][name] 

dnsdomainname 


DESCRIPTION 

hostname is the program that is used to either set the hostname or display the current host or domain name of the system. 
This name is used by many of the networking programsto identify the machine 

When called without any arguments the program displays the current name as set by the hostname command. You can 
change the output format to display always the short or the long hostname (FQD N). When called with arguments, the 
program will set the value of the hostname to the value specified. This usually is done only once, at system startup time, by 
the /etc/rc.d/rc.ineti configuration script. 

N ote that only the superuser can change the hostname. 

If the program was called as dnsdomainname, it will show the domain name server (DNS) domain name. You can't change the 
DNS domain name with dnsdomainname. (Seethefollowing subsection.) 


OPTIONS 

-d, - -domain 

-F, - -file filename 
-f, --fqdn, --long 

-h, --help 
-s, --short 
-v, --version 

FILES 


D isplay the name of theDN S domain. Don't use the com-mand domainname to get the D N S 
domain name because it will show the N IS domain name and not theDN S domain name. 

Read the hostname from the specified file Comments (lines starting with a#) are ignored. 
Display the FQDN (fully-qualified domain name). An FQDN consists of a short hostname and 
theD N S domain name Unless you are using bind or N IS for host lookups, you can change the 
FQD N and theDN S domain name (which is part of the FQDN) in the /etc/hosts file. 

Print a usage message on standard output and exit successfully. 

D isplay the short hostname 

Print version information on standard output and exit successfully. 


/etc/hosts 
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AUTHOR 


Peter T Obi as, (tobiasOserver. et - inf. f ho - emden. de) 


Linux, 28July 1994 


hpedtoppm v0.3 

hpedtoppm vO.3— Convert a Photo-CD file into a portable pixmap 

SYNOPSIS 

hpedtoppm [options] ped-file [ppm-file] 


DESCRIPTION 

hpedtoppm reads a Photo-CD image file or overview file and outputs a portable pixmap. I mage files you can find on the 
Photo-CD in photo_cd/images are named asimgnnnn .pcd, where nn nn is a 4-digit-number. T he 0 verview file is at photo_cd/ 
overview, pcd. If there is no ppm-file given, output will be printed to stdout. hpedtoppm stands for "H admut's pedtoppm" to 
make it distinguishable in case someone else is building the same thing and calling it pedtoppm. 


OPTIONS 


-S 

•d 


-r 

-1 

-a 


-1 J -Base/16 | -128x192 

-2 J -Base/4 J -256x384 
-3 | -Base | -512x768 
-4 J -4Base | -1024x1536 
-5 | -16Base | -2048x3072 
-0 | -Overview j -0 


-yee 


Give some information from thefileheader to stderr. It works only for image files. (It is not 
working correctly, just printing some strings.) 

Apply simple sharpness-operator on the luma channel. 

Do not show the complete image, but only the decompressed difference. It works only on 
the4Baseand the 16Baseresolution. It does not have any deeper sense, but it was simple to 
implement and it shows what causes different sizes of image files. 

Rotate the picture clockwise for portraits. 

Rotate the picture counter-clockwise for portraits 

Try to find out the image orientation. This doesn't work for overview files yet. It is very 
experimental and depends on onebyte. Please tell me if it doesn't work. 

Overskip mode. Workson Bas^l6, Bas^4, Base, and 4Base. In Photo-CD images, the 
luma channel is stored in full resolution, thetwo chroma channels are stored in half 
resolution only and have to be interpolated. In the Overskip mode, the chroma channels of 
the next higher resolution are taken instead of interpolating. T o see the difference, generate 
oneppm with and one ppm without thisflag. Usepnmarith to generate the difference image of 
these two images. Call ppmhist for thisdifference or show itwith xv (push theH istEq 
button in the color editor). 

E xtract theBas^ 16 size picture (size 128x192 pixels). N ote that you can only give one size 
option. 

Extract the Bas^4 size picture. 

Extract the B ase size pi cture. 

E xtract th e 4 B ase si ze p i ctu re. 

E xtract th e 16 B ase si ze p i ctu re. 

Extract all pictures from an Overview file. A ppm filename must be given. If the given name 
is too, the files are named toonnnn, where nnnn is a 4-digit number. They are stored in 
Bas^l6 format, so they are extracted in thisformat. 

Suppress the yee to rgb conversion. This is experimental only. You can usethisand apply 
ppmtorgb3 on the file Then you will get three pgm files, one luma and two chroma files. 




httpd 



BUGS 

I still don't have enough information about the Photo-CD to take care of all data structures. The information I have is quite 
vague and this program was developed by staring at thehexdumpsand using the famous trial-and-error-method.:-) If 
anything doesn't work, please send me a report and perhaps you could try to find out why it doesn't work. 

SEE ALSO 

ppm(5), ppmquant(l), ppmtopgm(l), ppmhist(l), pnmarith(l), ppmtorgb3(l), xv(l) 

AUTHOR 

Copyright© 1992 by H admut Danisch (danisch@ina.uka.de). Permission to use and distribute this software and its 
documentation for noncommercial use and without fee is hereby granted, provided that the preceding copyright notice 
appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. 

This software may not be sold in any way. This software is not public domain. 

28 N ovember 1992 


httpd 

httpd— Apache Hypertext T ransfer Protocol server 

SYNOPSIS 

httpd [ -vX? ][-d serverroot ] [-f config ] 

DESCRIPTION 

httpd istheApacheH ypertextT ransfer Protocol (HTTP) server process. The server may be invoked by the Internet daemon 
inetd(lM ) each time a connection to the HTTP service is made, or alternatively it may run as a daemon. 

OPTIONS 

-d serverroot 

-f config 

-X 

-v 
_? 

FILES 

/ usr/local/etc/httpd/conf/httpd.conf 
/ usr/local/etc/httpd/conf/srm.conf 
/usr/local/etc/httpd/conf/access.conf 
/usr/local/etc/httpd/conf/mime.types 
/usr/local/etc/httpd/logs/error_log 
/usr/local/etc/httpd/logs/access_log 
/usr/local/etc/httpd/logs/httpd.pid 

SEE ALSO 

inetd(lm) 

Documentation for the Apache HTTP server is available from http://www.apache.org. 


Set the initial value for the serverRoot variableto serverroot. Thiscan be overridden by theserverRoot 
command in the configuration file The default is/usr/iocai/etc/httpd. 

Execute the commands in the file conf i g on startup. If conf i g does not begin with a /, then it is taken to 
bea path relative to theserverRoot. T he default isconf/httpd.conf. 

Run in singleprocess mode, for internal debugging purposes only; the daemon does not detach from the 
terminal or fork any children. Do not us this mode to provide ordi nary W eb service. 

Print the version of httpd, and then exit. 

Print a list of the httpd options, and then exit. 


October 1995 
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icontopbm 

icontopbm— Convert a Sun icon into a portable bitmap 

SYNOPSIS 

icontopbm [iconfile] 

DESCRIPTION 

icontopbm readsaSun icon asinput and produces a portable bitmap as output. 

SEE ALSO 

pbmtoicon(l), pbm(5) 

AUTHOR 

Copyright® 1988 byjef Poskanzer 

31 August 1988 


ident 

ident— Identify RCS keyword strings in files 

SYNOPSIS 

ident [ -q ] [-V ] [f i! e ... ] 

DESCRIPTION 

ident searches for all instances of the pattern $ keyword : text $ in the named files or, if no files are named, the standard 
input. 

These patterns are normally inserted automatically by the RCS command co(l), but can also be inserted manually. The 
option -q suppresses the warning given ifthereareno patterns in a file The option -v prints ident 's version number. 

ident works on text files as well as object files and dumps. For example if the C program in t.c contains 

#include <stdio.h> 
static char const rcsid[] = 

"$Id: f.c,v 5.4 1993/11/09 17:40 eggert Exp $"; 
int main() { return printf("%s\n", rcsid) == EOF; } 

and t .c iscompiled into f .o, then the command 
ident f.c f.o 
will output 
f.c: 

$Id: f.c.v 5.4 1993/11/09 17:40 eggert Exp $ 
f.o: 

$Id: f.c.v 5.4 1993/11/09 17:40 eggert Exp $ 

If a C program defines a string like the rcsid but does not use it, iint(l) may complain, and someC compilers will optimize 
away the string. The most reliable solution isto have the program use the rcsid string, as shown in theexample. 

ident finds all instances of the $ keyword : text $ pattern, even if keyword is not actually an RCS-supported keyword. This 
gives you information about nonstandard keywords like $xconsortium$. 
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KEYWORDS 

H ere is the list of keywords currently maintained by co(l). All times are given in Coordinated U niversal TimefUTC, 
sometimes called GMT by default), but if the files were checked out with co's-zzone option, times are given with anumeric 
timezoneindication appended. 

$Author$ The login name of the user who checked in the revision. 

$Date$ Thedateand timetherevision waschecked in. 

$Header$ A standard header containingthefull pathname of the RCS file the revision number, thedateand time, 

the author, the state, and the locker (if locked). 

$id$ Same as$Header$, except that the RC S filename iswithout a path. 

$Locker$ The login name of the user who locked the revision (empty if not locked). 

$Log$ The log message supplied during checkin. For ident's purposes, this is equivalent to $Rcstiie$. 

$Name$ The symbolic name used to check out the revision, if any. 

$Rcst iie$ T he name of the RC S file without a path. 

$Revision$ The revision number assigned to the revision. 

$sounce$ Thefull pathname of the RC S file. 

$state$ The state assigned to the revision with the-s option of rcs(l) or ci(l). 

co( 1) represents the following characters in keyword values by escape sequences to keep keyword strings well formed. 

Character 
T ab 

N ewline 
Space 
$ 

\ 

IDENTIFICATION 

Author: Walter F.Tichy 

M anual Page Revision: 5.4; Release date September 11,1993. 

Copyright© 1982,1988,1989 Walter F. Tichy. Copyright© 1990,1992,1993 Paul Eggert. 

SEE ALSO 

ci(l), co(l), rcs(l), rcsdiff(l), rcsintro(l), rcsmerge(l), rlog(l), rcsfile(5) 

Walter F. Tichy, RCS—A System for Version Control, Software-Practice & Experience 15, 7 (July 1985), 637-654. 

GNU, 9 November 1993 

ilbmtoppm 

ilbmtoppm— Convert an ILBM file into a portable pixmap 

SYNOPSIS 

ilbmtoppm [-verbose][-ignore<chunkID>] [-isham]-isehb][-adjustcolors][ILBMfile] 

DESCRIPTION 

ilbmtoppm reads an IFF ILBM file as input and produces a portable pixmap as output. Supported ILBM types are N ormal 
ILBM swith 1-16 planes. 


Escape Sequence 

\t 

\n 

\040 

\044 

\\ 
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Amiga Extra H alfbrite (EH B) 

Amiga HAM with 3-16 planes 
24-bit 

M ultiplatte (normal or H AM ) pictures 
Colormap (bmhd and cmap chunk only, nPianes = 0 ) 

Unofficial direct color; 1-16 planes for each color component. 

Chunks used: bmhd, cmap, camg (only HAM and EH B flags used), pchg, body unofficial dcol chunk to 

identify direct color ILBM 

C hunks ignored: grab, dest, sprt, crng, ccrt, clut, dppv, drng, epsf 

Other chunks (ignored but 

displayed in verbose mode): name, auth, (d), anno, dpi 

Unknown chunks are skipped. 


OPTIONS 

-verbose 

-ignore <chunkID> 
-isham | -isehb 

-adjustcolors 


Give some information about thelLBM file. 

Skip a chunk. <chunkiD> is the 4-letter iff chunk identifier of the chunk to be skipped. 

T reat the i nput fi le as a ham or Extra H alfbrite pi cture, even if these flags or not set i n the camg 
chunk (or if there is no camg chunk). 

If all colors in the cmap have a value of lessthen 16, iibmtoppm assumes a 4-bit colormap and gives a 
warning. W ith this option, the colormap is scaled to 8 bits 


BUGS 

T he multi palette PC H G BigLinechanges and H uffman decompression code are untested. 

REFERENCES 

Amiga ROM Kernel ReferenceM an ual— Devices (3rd Ed.). Addison Wesley, ISBN 0-201-56775-X. 

SEE ALSO 

ppm(5), ppmtoilbm(l) 

AUTHORS 

Copyright© 1989 byjef Poskanzer. 

M Odified 0 Ctober 1993 by I ngo W ilken (lngo.Wilken@informatik. uni-Oldenburg. de) 

4 October 1993 


imake 

imake— C preprocessor interface to the make utility 

SYNOPSIS 

imake [ -Ddefine ] [-Id i r ] [ -Tt empl at e ][-f filename ] [ -C filename ] [-s filename ] 

[-e ][-v ] 

DESCRIPTION 

imake is used to generate Makefiles from a template, a set of cpp macro functions, and a per-di rectory input file called an 
imakefiie. This allows machine dependencies (such as compiler options, alternate command names, and special make rules) to 
be kept separate from the descriptions of the various items to be bui It. 



imake 



OPTIONS 


The following command-line options may be passed to imake: 


-Ddef i ne 

-Idi rectory 

-Tt e mp I ate 

-f f i I e n a me 
-C f i I ename 

-s f i I ename 

-e 

-v 


Thisoption is passed directly to cpp. It istypically used to set directory-specific variables. For example, the 
X W indow System uses this flag to set topdir to the name of the directory containing the top of the core 
distribution and curdir to the name of the current directory, relative to the top. 

Thisoption is passed directly to cpp. It istypically used to indicate the directory in which the imake 
template and configuration files may be found. 

Thisoption specifies the name of the master template file (which is usually located in the directory 
specified with -i) used by cpp. The default is imake.tmpi. 

Thisoption specifies the name of the per-directory input file. The default isimakefiie. 

Thisoption specifies the name of the .c file that is constructed in the current directory. The default is 
Imakefile.c. 

Thisoption specifies the narneofthemake description fileto be generated but make should not beinvoked. 
If the filename isa hyphen (-), the output iswritten to stdout. The default isto generate, but not execute, 
a Makefile. 

Thisoption indicates the imake should execute the generated Makefile. The default isto leave this to the 
user. 

Thisoption indicates that imake should print the cpp command line that it is using to generate the 
Makefile. 


HOW IT WORKS 

imake invokes cpp with any -i or -d flags passed on the command line and passes the name of a file containing the following 
three lines: 

#define IMAKE_TEMPLATE "Imake.tmpl" 

#define INCLUDE!MAKEFILE <Imakefile> 

#include IMAKE_TEMPLATE 

where imake.tmpi and makefile may be overridden by the-T and -f command options, respectively. 

TheiMAKE_TEMPLATE typically reads in a file containing machine-dependent parameters (specified as cpp symbols), a site- 
specific parameters file, a file defining variables, a file containing cpp macro functions for generating make rules, and finally 
the makefile (specified by includeimakefile) in the current directory. The makefile uses the macro functions to indicate 
what targets should be built; imake takes careof generating theappropriate rules. 

make configuration files contain two types of variables imake variables and make variables. The imake variables are interpreted 
by cpp when make is run. By convention they are mixed case. The make variables are written into the Makefile for later 
interpretation by make. By convention make variables are uppercase. 

The rules file (usually named make, rules in the configuration directory) contains a variety of cpp macro functions that are 
configured according to the current platform, make replaces any occurrences of the strings with a newline to allow macros 
that generate more than one line of make rules. For example, when called with program_target(foo, fool .0 f 002 . 0 ), the 
macro: 

#define program_target(program, objlist) @@\ 

program: objlist 

$(CC) -0 $@ objlist $(LDFLAGS) 

will expand to 

foo: fool .0 foo2.o 

$(CC) -0 $@ fool.O f002 .0 $(LDFLAGS) 

imake also replaces any occurrences of the word xcomm with the character # to permit placing comments in the Makefile 
without causing invalid directive errors from the preprocessor. 
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Some complex imake macros require generated make variables local to each invocation of the macro, often because their value 
depends on parameters passed to the macro. Such variables can be created by using an imake variable of the form xvARdetn, 
wheren is a single digit. A unique make variable will be substituted. Later occurrences of the vari able xvARusen will be replaced 
by the variable created by the corresponding xvARdefn. 

On systems whose cpp reduces multiple tabs and spaces to a single space, imake attempts to put back any necessary tabs (make 
is very picky about the difference between tabs and spaces). For this reason, colons (:) in command lines must be preceded 
by a backslash (\). 

USE WITH THE X WINDOW SYSTEM 

TheX Window System uses imake extensively, for both full builds within the source tree and external software. As men¬ 
tioned earlier, two special variables, topdir and curdir, are set to make referencing files using relative path names easier. For 
example, the following command is generated automatically to build the Makefile in the directory iib/x/ (relative to the top 
of the sources): 

% /config/imake -I/config \ 

-DTOPDIR=../../. -DCURDIR=./lib/X 

When buildingX programs outside the source tree, aspecial symbol useinstaiied is defined and topdir and curdir are 
omitted. If the configuration files have been properly installed, the script xmkmf(l) maybeused. 

INPUT FILES 

FI ere is a summary of the files read by imake as used by X. The indentation shows which files include which other files. 

Imake.tnpl generic variables 

site.def site-specific, BeforeVendorCF defined 

.cf machine-specific 

Lib.rules shared library rules 

site.def site-specific, AfterVendorCF defined 

Imake.rules rules 

Project.tmpl X-specific variables 

Lib.tmpl shared library variables 

Imakefile 

Library.tmpl library rules 
Server.tmpl server rules 
Threads.tmpl multi-threaded rules 

N otethat site.def is included twice, once before the *.cf file and once after. Although most site customizations should be 
specified after the*. cf file some, such as the choice of compiler, need to be specified before, because other variable settings 
may depend on them. 

Thefirst time site.def is included, the vari able BeforeVendorCF is defined, and the second time, the vari able Af terVendorCF is 
defined. All code in site.def should be inside a #ifdef for one of these symbols. 

FILES 

imakefile.c T emporary input file for cpp 
/tmp/imf .xxxxxx Temporary Makefile for -s 

/tmp/nf .xxxxxx T emporary imakefile if specified imakefile uses# comments 
/iib/cpp D efault C preprocessor 

SEE ALSO 

make(l), xmkmf(l) 

S. I. Feldman, Make- A Program forMaintainingComputerPrograms 
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ENVIRONMENT VARIABLES 

The following environment variables may beset; however, their use is not recommended as they introduce dependencies that 
are not readily apparent when imake is run. 

imakeinclude If defined, this should bea valid i nclude argument for the C preprocessor. Example 
-I/usr/include/local 

Actually, any valid cpp argument will work here. 
imakecpp If defined, this should bea valid path to a preprocessor program. Example 

/usr/local/cpp 

By default, imake will use /lib/cpp. 

imakemake If defined, this should beavalid path to a makeprogram, such as 
/usr/local/make 

By default, imake will use whatever make program is found using execvp(3). This variable is only used if the 
-e option is specified. 

AUTHORS 

Todd Brunhoff, Tektronix and M IT Project Athena 
Jim Fulton, M IT X Consortium 

X Veraon 11 Relea9s6 

imgtoppm 

imgtoppm— ■ Convert an img-whatnot file into a portablepixmap 

SYNOPSIS 

imgtoppm [imgfile] 

DESCRIPTION 

imgtoppm reads an img-whatnot file as input and produces a portable pixmap as output. T he img-whatnot toolkit is available for 
FTP on venera.isi.edu, along with numerous images in thisformat. 

SEE ALSO 

ppm(5) 

AUTHOR 

Based on a simple conversion program posted to comp, graphics by Ed Falk. 

Copyright© 1989 byjef Poskanzer. 

5 September 1989 

inews 

inews— Send a U senet article to the local news server for distribution 

SYNOPSIS 

inews [ -h ][-D ][-0 ][-R ][-S ] [headerf I ags ] [ i n p u t ] 
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DESCRIPTION 

mews reads a U senet news article (perhaps with headers) from the named file or standard input if no file is given. It adds 
some headers and performs some consistency checks. If the article does not meet these checks (for example, too much 
quoting of old articles, or posting to nonexistent newsgroups), then the article is rejected. If it passes the checks, inews sends 
the article to the local news server as specified in theinn.conf(5) file for distribution. 

In the standard mode of operation, the input consists of the article headers, a blank line, and the message body. For com¬ 
patibility with older software, the-h flag must be used. If there are no headers in the message, then this flag may be omitted. 

Several headers may be specified on the command line, shown in the synopsis above as header flags. Each of these flags takes 
a single parameter; if thevalueismorethan oneword (for example, almost all Subject lines) then quotes must be used to 
prevent the shell from splitting it into multiple words. The options, and their equivalent headers, are as follows: 

a Approved 

c Control 

d Distribution 

e Expires 

f From 

w Followup-T o 

n N ewsgroups 

r Reply-T o 

t Subject 

F References 

o Organization 

x Path prefix 

The Path header is built according to the following rules. If the-x flag is used, then its value will be the start of the header. 
Any other host will see the site in the header, and therefore not offer the article to that site. If the pathhost configuration 
parameter is specified in theinn.conf(5) file then it will be added to the Path. Otherwise, if the server configuration 
parameter is specified, then thefull domain name of the local host will be added to the Path. The Path will always end 
not-for-mail. 

T he default 0 rganization header will be provided if none is present in the article or if the -o flag is not used. T o prevent 
adding the default, use the-o flag. 

As a debugging aide if the -d flag is used, the consistency checks will be performed, and the article will be sent to the 
standard output, rather then sent to the server. 

For compatibility with C News, inews accepts, but ignores, the -a, -v, and -w flags. The C N ews-N flag istreated as the -d flag. 

If afile named .signature exists in the user's home directory, inews will try to append itto the end of the article. If thefile 
cannot be read, or if it is too long (for example, more than four lines or one standard I/O buffer), or if some other problem 
occurs, then the article will not be posted. T o suppress this action, use the-s flag. 

If the -r flag is used then inews will reject any attempts to post control messages. 

If an unapproved posting is made to a moderated newsgroup, inews will try to mail the article to the moderator for posting. 
It uses the modenators(5) file to determine the mailing address. If no address is found, it will usetheinn.conf file to 
determine a "last-chance" host to try. 

If the N N T P server needsto authenticate the client, inews will usetheNNTPsendpass-word(3) routineto authenticate itself. In 
order to do this, the program will need read access to thepasswd.nntp(5) file. This is typically done by having thefile group- 
readable and making inews run setgid to that group. 

inews exits with a zero status if the article was successfully posted or mailed, or with a nonzero status if the article could not 
be delivered. 



info 


269 

Since inews will spool its input if the server is unavailable, it is usually necessary to run rnews(l) with the-u flag on a regular 
basis, usually out of cron(8). 

HISTORY 

W ritten by Rich $alz (rsaiz@uunet.uu.net) for InterNetN ews 

SEE ALSO 

moderators(5), inn.conf(5). rnews(l) 

info 

info— G N U's hypertext system 

SYNOPSIS 

info [ --option-name option-value ] enu-item... 

DESCRIPTION 

TheGNU proj ect has a hypertext system called info that allows the same source file to be either printed as a paper manual, 
or viewed using info. It ispossibleto usetheinfo program from insideEmacs, or to usethestandaloneversion described 
here. This manual page gives a brief summary of its capabilities. 

OPTIONS 

--directory directory-path Add d i rectory- path to the list Of directory paths Searched when info needs to find a file. 

You may issue - directory multiple times. Alternatively, you may specify a value for the 
environment variable infopath; if --directory isnot given, the value of infopath isused. 

The value of infopath isa colon-separated list of directory names. If you do not supply 
either infopath or --di rectory-path, info uses a default path. 

-f filename Specify a particular info fileto visit. By default, info visits the file dir; if you usethis 

option, info will start with (filename)top as the first file and node. 

-n nodename Specify a particular node to visit in the initial file that info loads. This is especially useful in 

conjunction with -file. You may specify --node multiple times. 

-o fi i e D i rect output to file instead of starting an interactive info session. 

-h Producea relatively brief description of the available info options. 

--version Print the version information of info and exit. 

menu-item info treats its remaining arguments as the names of menu items. The first argument isa 

menu item in theinitial node visited, whilethesecond argument isa menu item in the first 
argument's node. You can easily move to the node of your choice by specifying the menu 
names that describe the path to that node. For example, info emacs buffers first selects the 
menu item emacs in the node (dir)Top, and then selects the menu item buffers in the node 
(emacs)Top. 

COMMANDS 

In info, thefollowing commands are available: 
h Invokethe info tutorial. 

? Get a short summary of info commands. 

h Select the info node from the main directory; this is much more complete than just using?, 

ctri-g Abort whatever you are doing, 

ctri-i Redraw the screen. 
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Selecting other nodes: 

n Move to the next node of this node, 

p M ove to the previous node of this node, 

u M ove to this node's up node. 

m Pick a menu item specified by name. Picking a menu item causes another node to be selected. You do not need to 

type a complete nodename; if you type a few letters and then a space or tab, into will try to fill in the rest of the 
nodename. If you ask for further completion without typing any more characters, you'll be given a list of 
possibilities; you can also get the list with ?. If you typeafew characters and then hit Enter, into will try to do a 
completion, and if it isambiguous, usethefirst possibility. 

t Follow a cross reference. You are asked for the name of the reference, using command completion as form. 

1 Move to the last node you were at. 

M ovingwithin a node 
space Scroll forward a page. 

del Scroll backward a page, 

b Go to the beginning of this node. 

Advanced commands: 


q 

i 

2-5 


g 

S 


M-x print-node 


Q uit info. 

Pick first item in node's menu. 

Pick second to fifth item in node's menu. 

M ove to node specified by name. You may include a filename as well, as (filename)nodename. 

Search through this into file for a specified string, and select the node in which the next occurrence is 
found. 

Pipe the contents of the current node through thecommand in the environment variable 
info_print_command. If the variable does not exist, the node is simply piped to ipr. 


ENVIRONMENT 

INFOPATH 

INFO_PRINT_COMMAND 


A co I on-separated list of directories to search for info files. Used if -directory isnot given. 
Thecommand used for printing. 


SEE ALSO 

emacs(l) 

AUTHOR 

Brian Fox, Free Software Foundation (bfox@ai.mit.edu) 

MANUALAUTHOR 

Robert Lupton (rhl@astro.princeton.edu); updated by Robert J. Chassell (bob@gnu.ai.mit.edu). 

7 December 1990 


innconfval 

innconfvai— Get an InterNetNews configuration parameter 

SYNOPSIS 


innconfval [ -f ] [parameter ... ] 
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DESCRIPTION 

innconfvai prints the values of the parameters specified on the command line. Values are retrie/ed from theinn.conf(5) file 
and are described there. 

Values are retrieved by using the Getconfigvaiue routine, or GetFiieConfigvaiue if the -f flag isused. Both are descri bed in 
libinn(3). 

HISTORY 

W ritten by Rich $alz (rsaiziuunet.uu.net) for InterNetN ew/s 

SEE ALSO 

libinn(3), inn.conf(5) 

insmod 

insmod— Install loadable modules (aout and elf format) 

SYNOPSIS 

insmod [ -fkmsxv ] [ -o internal_name ] object_file [ symbol=value ... ] 

DESCRIPTION 

insmod installs a loadable module in the kernel. 

insmod tries to load a module into the kernel, and resolves all symbols from the exported kernel symbols with version 
information, if available The module will get its name by removing the .0 extension from thebasenameof the object file. If 
the .0 extension is omitted, insmod will attempt to locate the module in some common default directories. If the environ¬ 
ment contains the variable modpath, where all directories are separated with insmod will look in these directories for the 
module, in the specified order. 

It is possible to load unversioned modules in a versioned kernel, and all combinations of these. 

It is also possi ble to load ELF modulesinto an a. out kernel, and all combinationsof these. 

It is possi ble to stack modules, that is, let one module use a previously loaded module. All modules that are referenced are 
updated with this reference. This ensures that a module can't be unloaded if there is another module that refers to it. 

It is possi ble to change integer values in the module when loading it. This makes it possi ble to tune the module. 

The options are as follows: 

-f The-t option tries to load the module even if the kernel or symbol versions differs from the 

version expected by the module. A warning will be issued if the module is locked to a 
specific kernel version that differs from the current version. 

-k Thisoption should really only be used by modprobe, to indicatethat the module insertion 

was requested by kerneid. All modules inserted using this option will be subject to 
autoremoval by the kerneid utility if they have been unused for more that a minute. (The 
usage count is zero and no modules depend on this module.) If the kernel is not kerneid- 
aware the module will be rejected by the kernel. Just load it without the -k option, and all 
should be well. 

-m T he -m option will make insmod output a load map, that will make it easier to debug your 

modules after a kernel panic, thanksto D erek Atkins (wariord®MiT.EDu). 

-0 The-o option allows the module to be named to an explicit name instead of having a name 

derived from the name of the object file. N ote that thisoption can also beplaced after the 
module name, so that the syntax of insmod looks more similar to id. 
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symboi=vaiue[ .value] ... T he values of all i nteger or character pointer symbols in the module can be changed at load¬ 
time by naming a symbol and giving the new value(s). If thesymbol isdefined as an array of 
integers or character pointers, the elements in the array can be initialized by giving the 
values separated by commas. Specific array entries can be skipped by omitting the value, as 
in symbols a i uei,,vaiue2. Each integer value can be given as a decimal, octal, or hexadeci¬ 
mal value: 17 , 021 , or 0 x 11 . If the first character in the given value is nonnumeric, the value 
is interpreted as a string. Thesymbol is assumed to be a character pointer, which will be 
initialized to point to the string. Extra space in the module will deallocated for the string 
itself. N ote the syntax: no spaces are allowed around the = or, signs! 

-s With this option, insmod will produce debugging information and error messages using the 

sysiog facility. (Also used by kerneid, if you have installed it.) 

-v If you want verbose information from the loading, select this option. 

-x The no-export flag, which will inhibit the default insmod behavior— inserting all the 

module's external symbolsinto the kernel symbol table. N ote that the kernel will still 
update the references that the module makes to previously loaded modules. 

SEE ALSO 

rmmod(l), modprobe(l), depmod(l), lsmod(l), ksyms(l), modules(2), genksyms(8) 

HISTORY 

The module support was first conceived by Anonymous (asfar as I know). Linux version by BasLaarhoven (bas@vimec.rn). 
0.99.14 version byjon Tombs(jon@gtex 02 .us.es). Extended by Bjorn Ekwall (bj 0 rn@biox.se). ELF help from Eric 
Y Oungdale (eric@aib.com). 

BUGS 

insmod relies on the "fact" that symbols, for which one wants to change the value, are defined as integers or character 
pointers, and that sizeof(int) == sizeoffchar *). 

Linux, 14 May 1995 

install 

install— Copy files and set their attributes; GNU file installer 

SYNOPSIS 

install [options] [-s] [--strip] source dest 
install [options] [-s] [--strip] source... directory 
install [options] [-d,--directory] directory... 

Options: 

[-c] [-g group] [ -m mode] [-0 owner ] [- -group=group] [- -mode=mod e] 

[--owner=owner ] [--help] [--version] 

DESCRIPTION 

Thismanual page documents the GN U version of install, install copies files and setstheir permission modes and, if 
possible their owner and group. Used similarly to cp; typically used in Makefiles to copy programsinto their destination 
directories. It can also beused to create the destination directories and any leading directories, and to set the final directory's 
modes. It refuses to copy files onto themselves. 
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OPTIONS 


-C 

-d, --directory 


-g, - -group group 


-m, --mode mode 


-o, --owner owner 

-s, --strip 
--help 
--version 


Ignored; for compatibility with old UNIX versions of install. 

Create each given directory and itsleading directories, if they do not already exist. Set theowner, 
group, and mode as given on the command line or to the defaults. Also gives any leading directories 
that are created those attributes. T his is different from the SunO S 4 .x install, which gives 
directories that it creates the default attributes. 

Set the group ownership of the installed file or directory to the group ID of group (default is 
process's current group), group may also be a numeric group ID. 

Set the permission mode for the installed file or directory to mode, which can be either an octal 
number, or a symbolic mode as in chmod, with 0 as the point of departure. The default models 

0755. 

If run as root, set the ownership of the installed file to theuser ID ofowner (default is root), owner 
may also be a numeric user ID. 

Strip the symbol tables from installed programs. 

Print a usage message on standard output and exit successfully. 

Print version information on standard output and exit successfully. 

GNU File Utilities 


installit 

installit— File/directory installation tool 

SYNOPSIS 

installit [ -o owner ][-g group ][-0 owner ][-G group ][-m mode ][-b backup ] 

[-s ][-t ] source destination 

DESCRIPTION 

installit puts a Copy Of source into the Specified destination. 

If source is a period, then destination is taken to be the name of a directory that should be created. Otherwise, source is 
taken to name an existing file and desti nati on may be either a file or directory; it is interpreted according to the same rules 
ascp(l). 

If desti nati on namesa preexisting file, it will be removed before the copy is done. T 0 make a backup copy, use the-b flag; 
the existing file will be renamed to have the specified extension. If source and desti nati on are the same string, or if the two 
files are identical, then no copying is done, and only the - 0 , -g, -m, and -s flags are processed. In thiscase, the modification 
time on the desti nati on will be updated using touch(l) unlessthe-n (don't touch) flag is used. 

After the desti nati on has been created, it is possible to set the owner, group, and mode that it should have. This is done by 
using the-0, -g, and -m flags, respectively. The-0 and -g flags set theowner and group only if installit is being run by root, 
as determined bywhoami(l). T 0 stnp(l) an installed executable, usethe-s flag. 

N otethat installit uses no special privileges to copy files from one place to another. 

BUG SAND LIMITATIONS 

FI ags can n ot be com bi ned. 

T he chown(8) command must exist in either the /etc or / usr/etc directory or the user's path. 

Thewhoami command must exist in the /usr/ucb directory or the user's path. 
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HISTORY 

W ritten by Rich $alz (rsaiz@uunet.uu.net) for InterNetNews. 

ispell, buildhash, munchlist, findaffix,tryaffix,icombine, 
ijoin 

ispell, buildhash, munchlist, findaffix, tryaffix, icombine, ijoin--I interactive spelling checking 

SYNOPSIS 

ispell [common-f I ags ][-M|-N][-Lcontext ] [-V] files 

ispell [common - f I ags] -1 

ispell [common-f I ags][-f file] [-s]-a| -A 

ispell [-d fi I e][-w chars] -c 

ispell [-d fi I e][-w chars] -e[e] 

ispell [-d file] -D 

ispell -v[v] 

common-flags:[-t][-n][-b][-x][-B][-C][-P][-m][-S] [-d file][-p f i I e][-w chars] 

[-W n][-T type] 

buildhash [-s] diet-file affix-file hash-file 

buildhash -s count affix-file munchlist [-1 aff-fi I e][—c conv-file] 

[-T s uf f i x][-s hash-file] [-D][-v][-w chars ] [fiI es ] findaffix [-pj-s][-f][-c] 

[-m mi n ] [-M max ] [-e el i m] [-t tabchar ][—1 I ow] [f i I es ] 

tryaffix [-p|-s] [-c] expanded-fiIe affi x[+addi t i on ] 

icombine [-T t ype ] [af f-fiI e ] 

ijoin [-s | -u ] join-options filel f i I e 2 

DESCRIPTION 

ispell is fashioned after the spell program from ITS (called ispeii on T wenex systems.) The most common usage is ispeii 
filename. In this case, ispeii will display each word which does not appear in the dictionary at the top of the screen and 
allow you to change it. If there are "near misses" i n the dictionary (words that differ by only a single letter, a missing or extra 
letter, a pair of transposed letters, or a missing space or hyphen), then they are also displayed on following lines. As well as 
near misses, ispeii may display other guesses at ways to make the word from a known root, with each guess preceded by 
question marks. Finally, the line containing the word and the previous line are printed at the bottom of the screen. If your 
terminal can display in reverse video, the word itself is highlighted. You have the option of replacing the word completely or 
choosing one of the suggested words. C ommands are si ngle characters as follows (case is ignored): 

r Replacethe misspelled word completely. 

Space Accepttheword thistimeonly. 

a Accepttheword for the rest of this ispeii session, 

i Accepttheword, capitalized as it is in the file and update private dictionary, 

u Accepttheword, and add an uncapitalized (actually, all lowercase) version to the private dictionary. 

0-n Replacewith oneof thesuggested words. 

l Look up words in system dictionary (controlled by thewoRDs compilation option), 

x Write the rest of this file, ignoring misspellings, and start next file. 

q Exit immediately and leavethefileunchanged. 

i Shell escape. 
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"l Redraw screen. 

'z Suspend ispeii. 

? Give help screen. 

If the -m switch is specified, a one-line mini-menu at the bottom of the screen will summarize these options. Conversely, the 
-n switch may be used to suppress the mini-menu. (Themini-menu is displayed by default if ispeii was compiled with the 
minimenu option, but these two switches will always override the default.) 

If the -l flag is given, the specified number is used as the number of lines of context to be shown at the bottom of the screen. 
(T he default is to calculate the amount of context as a certain percentage of the screen size.) T he amount of context is subject 
to a system-imposed limit. 

If the-v flag isgiven, characters that are not in the 7-bit AN SI printable character set will always be displayed in thestyle of 
cat -v, even if ispeii thinks that these characters are legal ISO Latin-1 on your system. This is useful when working with 
older terminals W ithout this switch, ispeii will display 8-bit characters as is if they have been defined as string characters for 
the chosen filetype. 

Besidesthe-i, -a, and -a options, N ormal mode accepts the following common flags on the command line: 

-t T he input file is in TeX orLaTeX format. 

-n Theinputfileisin nrotf/troff format. 

-b C reate a backup fi le by appendi ng . bak to the name of the i nput fi le 
-x Don't create a backup file 

-b Report run-together wordswith missing blanks as spelling errors 
-c C onsider run-together words as legal compounds. 

-p Don't generate extra root/affix combi nations. 

-m M ake possible root/affix combi nations that aren't in the dictionary. 

-s Sort the list of guesses by probable correctness. 

-dfiie Specify an alternate dictionary file. For example, use-d deutsch to choose a German dictionary in a German 
installation. 

-p f i i e Specify an alternate personal dictionary. 

-w chars Specify additional characters that can be part of a word. 

-w n Specify length of words that are always legal. 

-t type Assume a given formatter type for all files. 

The-n and -t options select whether ispeii runs in nrotf/troff (-n) orTeX/LaTeX (-t) input mode. (The default is 
controlled by the deftexflag installation option.) T eX/LaT eX mode is also automatically selected if an input file has the 
extension .tex, unless overridden by the-n switch. In TeX/LaTeX mode, whenever a backslash (\) is found, ispeii skips to 
the next whitespace or T eX/LaT eX delimiter. Certain commands contain arguments that should not be checked, such as 
labels and reference keys found in the \cite command, because they contain arbitrary, nonword arguments. Spell checking is 
also suppressed when in math mode. T hus, for example, given 

\chapter {This is a Ckapter} \cite{SCH86} 

ispeii will find "ckapter” but not "sch.” T he -t option does not recognizetheT eX comment character %, so comments are 
also spell checked. It also assumes correct LaT eX syntax. Arguments to infrequently used commands and someoptional 
arguments are sometimes checked unnecessarily. The bibliography will not be checked if ispeii was compiled with ignorebib 
defined. Otherwise, the bibliography will be checked but the reference key will not. 

References for the tib(l) bibliography system (text between a [. or <. and . ] or. >) will always be ignored in T eX/LaT eX mode. 
The-b and -x options control whether ispeii leaves a backup (.bak) file for each input file. 

The .bak file contains the precorrected text. If there are file opening/wri ting errors, the .bak file may be left for recovery 
purposes even with the-x option. The default for this option is controlled by the defnobackupflag installation option. 
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The-B and -c options control how ispeii handles run-together words, such as notthe for not the. If -b is specified, such 
words will be considered errors and ispeii will list variations with an inserted blank or hyphen as possible replacements. If 
-c is specified, run-together words will be considered to be legal compounds, so long as both components are in the 
dictionary, and each component is at least as long as a language-dependent minimum (three characters, by default). This is 
useful for languages such as German and Norwegian, where many compound words are formed by concatenation. (Note that 
compounds formed from three or more root words will still be considered errors). The default for this option is language- 
dependent; in a multilingual installation, the default may vary depending on which dictionary you choose. 

The-p and -m options control when ispeii automatically generates suggested root/affix combinationsfor possible addition to 
your personal dictionary. (These are the entries in the "guess" list that are preceded by question marks.) If -p is specified, 
such guesses are displayed only if ispeii cannot generate any possibilities that match the current dictionary. If -m isspecified, 
such guesses are always displayed. This can be useful if the dictionary has a limited word list, or a word list with few suffixes. 

H owever, you should be careful when using this option, as it can generate guesses that produce illegal words. The default for 
thisoption is controlled by the dictionary file used. 

T he -s option suppresses ispeii's normal behavior of sorting the list of possible replacement words. Some people may prefer 
this si nee it somewhat enhances the probability that the correct word will below-numbered. 

The-d option isused to specify an alternate hashed dictionary file, other than the default. If the filename does not contain a 
/, the library directory for the default dictionary file is prefixed; thus, to use a dictionary in the local directory -d ./xxx.hash 
must be used. This is useful to allow dictionaries for alternate languages. Unlike previous versions of ispeii, a dictionary of 
/dev/nuii is illegal because the dictionary contains the affix table. If you need an effectively empty dictionary, createaone- 
entry list with an unlikely string (for example, "qqqqq"). 

The-p option isused to specify an alternate personal dictionary file. If thefilename does not begin with /, shome is prefixed. 
Also, the shell variablewoRDnsi may beset, which renames the personal dictionary in the same manner. The command line 
overrides any wordlist setting. If neither the-p switch northewoRDLisT environment variableisgiven, ispeii will search fora 
personal dictionary in both the current directory and shome, creating one in shome if none is found. The preferred name is 
constructed by appending .ispeii to the base name of the hash file. For example if you use the English dictionary, your 
personal dictionary would be named .ispeii_engiish. However, if thefile .ispeii_words exists it wi II beused as the personal 
dictionary regardless of the language hash file chom This feature is included primarily for backwards compatibility. 

Ifthe-p option isnot specified, ispeii will look for personal dictionaries in both the current directory and the home 
directory. If dictionaries exist in both places, they will be merged. When words are added to the personal dictionary, they will 
be written to the current directory if a dictionary already existed in that place; otherwise, they will be written to the 
dictionary in the home directory. 

T he -w option may beused to specify characters other than alphabetics that may also appear i n words. For instance, -w "&■ 
will allow "AT&T” to be picked up. U nderscores are useful in many technical documents. There is an admittedly crude 
provision in thisoption for 8-bit international characters. N onprinting characters may be specified in the usual way by 
inserting a backslash followed by the octal character code, for example, \014for a form feed. Alternatively, if n appears in the 
character string, the (up to) three characters following are a decimal code, 0-255, for the character. For example, to include 
bells and form feeds in your words (an admittedly silly thing to do, but aren't most pedagogical examples): 

n007n012 

N umeric digits other than the three following n are simply numeric characters. Use of n does not conflict with anything 
because actual alphabetics have no meaning; alphabetics are already accepted, ispeii will typically beused with input from a 
file, meaning that preserving parity for possible 8-bit characters from the input text is okay. If you specify the -1 option, and 
actually type text from the terminal, this may create problems if your stty settings preserve parity. 

T he -w option may beused to change the length of words that ispeii always accepts as legal. N ormally, ispeii will accept all 
one-character words as legal, which is equivalent to specifying -w i. (The default for this switch is actually controlled by the 
minword installation option, so it may vary at your installation.) If you want all words to be checked against the dictionary, 
regardless of length, you might want to specify -w 0 . On the other hand, if your document specifies to accept all words of 
three letters or less, then regardless of the setting of thisoption, ispeii will only generate words that are in the dictionary as 
suggested replacements for words; this prevents the list from becoming too long. Obviously, thisoption can be very 
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dangerous, since short misspellings may be missed. If you use this option a lot, you should probably make a last pass without 
it before you publish your document, to protect yourself against errors 

The-T option is used to specify a default formatter type for use in generating string characters. This switch overrides the 
default type determined from the filename. The type argument may be either one of the unique names defined in the 
language affix file (such asnrotf) or a file suffix including the dot (for example -tex). If no -t option appears and no type 
can be determined from the filename, the default string character type declared in the language affix file will be used. 

The-i or list option to ispeii is used to produce a list of misspelled words from the standard input. 

The -a option is intended to be used from other programs through a pipe. In this mode, ispeii prints a one-line version 
identification message, and then begins reading lines of input. For each input line, a single line is written to the standard 
output for each word checked for spelling on the line. If the word was found in the main dictionary, or your personal 
dictionary, then the line contains only a*. If the word was found through affix removal, then the line contains a +, a space, 
and the root word. If theword was found through compound formation (concatenation of two words, controlled bythe-c 
option), then the line contains only a-. 

If theword is not in the dictionary, but there are near misses, then the line contains an &, a space, the misspelled word, a 
space, the number of near misses, the number of characters between the beginning of the line and the beginning of the 
misspelled word, a colon, another space, and a list of the near misses separated by commas and spaces. Following the near 
misses (and identified only by the count of near misses), if theword could be formed by adding (illegal) affixes to a known 
root, is a list of suggested derivations, again separated by commas and spaces. If there are no near misses at all, the line format 
is the same, except that the & is replaced by? (and the near-miss count is always zero). The suggested derivations following 
the near misses are in the form: 

[ p r e f i x + ] root [-prefix] [-suffix] [+suffix] 

(for example, "re+fry-y-hes" to get "refries") where each optional pfx and sfx isa string. Also, each near miss or guess is 
capitalized the same as the input word unless such capitalization is illegal; in the latter case each near miss is capitalized 
correctly according to the dictionary. 

Finally, if theword does not appear in the dictionary, and there are no near misses, then the line contains a#, a space, the 
misspelled word, a space, and the character offset from the beginning of the line. Each sentence of text input is terminated 
with an additional blank line, indicating that ispeii has completed processing the input line. 

These output lines can be summarized as follows: 

OK: 

Root: + <root> 

Compound: 

Miss: & <original><count><offset>: <miss>, <miss>, ..., <guess>, ... 

Guess: ? <original> 0 <offset>: <guess>, <guess>, ... 

N One: # <original> <offset> 

For example, a dummy dictionary containing the words fray, Frey, fry, and refried might produce thefollowing response to 
the Command echo frqy refries | ispeii -a -m -d ./test.hash: 

(#) International Ispeii Version 3.0.05 (beta), 08/10/91 
& frqy 3 0: fray, Frey, fry 
& refries 1 5: refried, re+fry-y+ies 

This mode is also suitable for interactive use when you want to figure out the spelling of a single word. 

The -a option works just like -a, except that if a line begins with the string "&inciude Files", the rest of the line is taken as 
the name of a file to read for further words. Input returns to the original file when the include file is exhausted. Inclusion 
may be nested u p to five deep. The key stri ng may be changed with the environment variable include string (the amper¬ 
sands, if any, must be included). 
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When in the-a mode, ispeii will also accept lines of single words prefixed with any of the following: *, &, @, +, #, i, %, 

orA line starting with * tells ispeii to insert the word into the user's dictionary (similar to the i command). A line 
starting with & tel Is ispeii to insert an all-lowercase version of the word into the user's dictionary (similar to theu com¬ 
mand). A line starting with @ causes ispeii to accept this word in the future (similar to the a command). A line starting with 
+, followed immediately by tex or nroft, will cause ispeii to parse future in put according the syntax of that formatter. A line 
consisting solely of a + will place ispeii in T eX/LaT eX mode (similar to the-t option) and - returns ispeii to nrotf/troft 
mode (but these commands are obsolete). H owever, string character type is not changed; the' command must beused to do 
this A line starting with ' causes ispeii to set internal parameters (in particular, the default string character type) based on 
the filename given in the rest of the line (A file suffix is sufficient, but the period must be included. Instead of a filename or 
suffix, a unique name, as listed in the language affix file, may be specified.) H owever, the formatter parsing is not changed; 
the + command must beused to change the formatter. A line prefixed with # will cause the personal dictionary to be saved. A 
line prefixed with i will turn on terse mode (explained later in this subsection), and a line prefixed with % will return ispeii 
to normal (non-terse) mode. Any input following the prefix characters+, or % is ignored, as is any input following the 
filename on a' line. To allow spell checking of lines beginning with these characters, a line starting with ■ has that character 
removed before it is passed to the spell checking code. It is recommended that programmatic interfaces prefix every data line 
with an up arrow to protect themselves against future changes in ispeii. 

T o summarize these 

* Add to personal dictionary 

@ Accept word, but leave out of dictionary 

# Savecurrent personal dictionary 

Set parameters based on filename 

+ E nter T eX mode 

ExitTeX mode 
i Enter terse mode 

% Exit terse mode 

Spell check rest of line 

In terse mode, ispeii will not print lines beginning with *, +, or-, all of which indicate correct words. Thissignificantly 
improves running speed when the driving program is going to ignore correct words anyway. 

The-s option is only valid in conjunction with the -a or -a options, and only on BSD-derived systems. If specified, ispeii 
will stop itself with asiGTSTP signal after each line of input. It will not read more input until it receives a sigcont signal. This 
may be useful for handshaking with certain text editors. 

The-t option is only valid in conjunction with the -a or -a options. If -f isspecified, ispeii will write its resultsto the 
given file rather than to standard output. 

The-v option causes ispeii to print its current version identification on thestandard output and exit. If the switch is 
doubled, ispeii will also print the options that it was compiled with. 

The-c, -e [ i - 4 ], and -d options of ispeii are primarily intended for use by themunchiist shell script. The -c switch causes a 
list of words to be read from thestandard input. For each word, a list of possible root words and affixes will be written to the 
standard output. Some of the root words will be illegal and must be filtered from the output by other means; themunchiist 
script does this Asan example, thecommand 

echo BOTHER | ispeii -c 

produces 

BOTHER BOTHE/R BOTH/R 

The-e switch is the reverse of -c; it expands affix flags to produce a list of words. For example, thecommand 

echo BOTH/R | ispeii -e 

produces 


BOTH BOTHER 
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An optional expansion level can also be specified. A level of 1 (-ei) is the same as -e alone. A level of 2 causes the original 
rooty affix combination to be prepended to the line: 

BOTH/R BOTH BOTHER 

A level of 3 causes multiple lines to be output, onefor each generated word, with the original rooty affix combination 
followed bytheword it creates: 

BOTH/R BOTH 
BOTH/R BOTHER 

A level of 4 causes a floating-point number to be appended to each of the level 3 lines, giving the ratio between the length of 
the root and the total length of all generated words including the root: 

BOTH/R BOTH 2.500000 
BOTH/R BOTHER 2.500000 

Finally, the -d flag causes the affix tables from the dictionary file to be dumped to standard output. 

Unless your system administrator has suppressed thefeatureto save space, ispeii is aware of the correct capitalizations of 
words in the dictionary and in your personal dictionary. As well as recognizing words that must be capitalized (such as 
George) and words that must be all capitals (such as NASA), it can also handle words with unusual capitalization (for 
example, IT-CorporTeX ). If aword iscapitalized incorrectly, the list of possibilities will include all acceptable capitaliza¬ 
tions. (M ore than one capitalization may be acceptable; for example, my dictionary lists both ITCorp and IT corp.) 

N ormally, this feature will not cause you surprises, but there is one circumstance you need to be aware of. If you use i to add 
aword to your dictionary that is at the beginning of a sentence (for example the first word of this paragraph if normally were 
not in the dictionary), it will be marked as "capitalization required.” A subsequent usage of this word without capitalization 
will be considered a misspelling by ispeii, and it will suggest the capitalized version. You must then compare the actual 
spellings by eye, and then typei to add the uncapitalized variant to your personal dictionary. You can avoid this problem by 
usingutoadd the original word, rather than i. 

Therulesfor capitalization are as follows: 

1. Any word may appear in all capitals, as in headings. 

2. Any word that is in the dictionary in all lowercase form may appear either in lowercase or capitalized (as at the 
beginning of a sentence). 

3. Any word that hasunusual capitalization (that is, it contains both cases and there isan uppercase character besides the 
first) must appear exactly asin the dictionary, except as permitted by rule 1. If the word isacceptable in all lowercase, it 
must appear thus in a dictionary entry. 

buildhash 

T he buildhash program builds hashed dictionary files forlater use by ispeii. Theraw word I ist (with affixflags) isgiven in 
diet-file, and the affix flags are defined by affix-file. The hashed output is written to hash-file. The formats of the two 
input files are described in ispeii(4). The-s (silent) option suppresses the usual status messages that are written to the 
standard error device. 

munchlist 

T he munchlist shell script is used to reduce the size of dictionary files, primarily personal dictionary files. It is also capableof 
combining dictionaries from various sources. The given files are read (standard input if no arguments are given), reduced to 
a minimal set of roots and affixes that will match the same list of words, and written to standard output. 

Input for munchlist contai ns of raw words (such as those from your personal dictionary files) or root and affix combinations 
(probably generated in earlier munchlist runs). Each word or root/affix combination must be on a separate line. 

The-D(debug) option leaves temporary files around under standard names instead of deleti ng them, so that the script can be 
debugged. W arning: Thisoption can eat up an enormous amount of temporary file space. 

The-v (verbose) option causes progress messages to be reported to stdem so you won't get nervous that munchlist has hung. 
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If the -s (strip) option is specified, words that are in the specified hash-file are removed from the word list. This can be 
useful with personal dictionaries. 

The-i can be used to specify an alternate affix-file for munching dictionaries in languages other than English. 

The-c option can be used to convert dictionaries that were built with an older affix file, without risk of accidentally 
introducing unintended affix combinations into the dictionary. 

The-T option allows dictionaries to be converted to a canonical string-character format. The suffix specified is looked up in 
the affix fi le (-1 switch) to determine the string-character format used for the input file; the output always uses the canonical 
string-character format. For example, a dictionary collected from T eX source files might be converted to canonical format by 
specifying -t tex. 

The-w option is passed on to ispeii. 

findaffix 

Thefindaffix shell script is an aid to writers of new language descriptions in choosing affixes. The given dictionary files 
(standard input if none are given) are examined for possible prefixes (-p switch) or suffixes (-s switch, the default). Each 
commonly occurring affix is presented along with a count of the number of times it appears and an estimateof the number 
of bytes that would be saved in a dictionary hash file if it were added to the language table. Only affixes that generate legal 
roots(found in theoriginal input) are listed. 

If the -c option isnot given, theoutput lines arein the following format: 
strip/add/count/bytes 

where strip isthe string that should be stripped from a root word before adding the affix, add istheaffixto be added, count 
is a count of the number of times that this strip/add combination appears, and bytes is an estimateof the number of bytes 
that might be saved in the raw dictionary file if this combination is added to the affix file The field separator in theoutput 
will be the tab character specified by the -t switch; the default is a slash (/). 

If the-c (clean output) option is given, the appearance of theoutput is made visually cleaner (but harder to post process) by 
changing it to 

-strip+add<tab>count<tab>bytes 

where strip, add, count, and bytes areas before, and <tab> represents the ASCII tab character. 

The method used to generate possible affixes will also generate longer affixes which have common headers or trailers. For 
example, the two words moth and mother will generate not only the obvious substitution +er but also -h+her and -th+ther 
(and possibly a/en longer ones, depending on the value of min). T 0 prevent cluttering the output with such affixes, any affix 
pair that shares a common header (or, for prefixes, trailer) string longer than eiim characters (default 1 ) will be suppressed. 
You may want to set eiim to a value greater than 1 if your language has string characters; usually, the need for this parameter 
will become obvious when you examine the output of your findaffix run. 

N ormally, the affixes are sorted according to the estimate of bytes saved. The-f switch may be used to cause the affixes to be 
sorted by frequency of appearance. 

T 0 save output file space, affixes which occur fewer than 10 times are eliminated; this limit may be changed with the-i 
switch. T he -m switch specifies a maximum affix length (default 8 ). Affixes longer than this will not be reported. (This saves 
on temporary disk space and makes the script run faster.) 

Affixes which generate stems shorter than three characters are suppressed. (A stem isthe word after thestrip string has been 
removed, and before the add string has been added.) This reduces both the running time and the size of the output fi le. This 
limit may be changed with the-m switch. The minimum stem length should only beset to 1 if you have a lot of free time 
and disk space(in therange of many days and hundredsof megabytes). 

Thefindaffix script requiresa nonblank field-separator character for internal use. Normally, this character is a slash (/), but 
if the slash appears as a character in the input word list, a different character can be specified with the-t switch. 

ispeii dictionaries should be expanded before being fed to findaffix; in addition, characters that are not in the English 
alphabet (if any) should be translated to lowercase. 
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tryaffix 

The tryaffix shell script is used to estimatetheeffectivenessof a proposed prefix (-p switch) or suffix (-s switch, the default) 
with a given expanded-file. 0 nly one affix can be tried with each execution of tryaffix, although multiple arguments can be 
used to describe varying forms of the same affix flag (for example, theD flag for English can add either d or ed depending on 
whether a trailing E is already present). Each word in the expanded dictionary that ends (or begins) with the chosen suffix (or 
prefix) has that suffix (prefix) removed; the dictionary is then searched for root words that match the stripped word. N or- 
mally, all matching roots are written to standard output, but if the -c (count) flag is given, only a statistical summary of the 
results is written. The statistics given area count of words the affix potentially applies to and an estimate of the number of 
dictionary bytes that a flag using the affix would save. The estimate will be high if the flag generates words that are currently 
generated by other affix flags (for example in English, bathers can be generated by either bath/x or bather/s). T he diction¬ 
ary fi le, expanded-tile, must already be expanded (using the -e switch of ispeii) and sorted, and things will usually work 
best if uppercase has been folded to lower with tr. 

Theaffix arguments are things to be stripped from the dictionary file to produce trial roots: for English, con (prefix) and mg 
(suffix) are examples. The addition parts of the argument are lettersthat would have been stripped off the root before adding 
theaffix. For example, in English the affix ing normally strips e for words ending in that letter (for example like becomes 
liking), so we might run 
tryaffix ing ing+e 
to cover both cases. 

All of the shell scripts contain documentation as commentary at the beginning; sometimes these comments contain useful 
information beyond the scope of this manual page. 

It ispossibleto install ispeii in such away as to only support ASCII range text if desired, 

icombine 

The icombine program is a helper for munchlist. It reads a list of words in dictionary format (roots plus flags) from the 
standard input, and produces a reduced list of standard output that combines common roots found on adjacent entries. 
Identical roots that have differing flags will have their flags combined, and roots that have differing capitalizationswill be 
combined in a way that only preserves important capitalization information. The optional aff-fiie specifies a language file 
that defines the character sets used and the meanings of the various flags. The -t switch can be used to select among 
alternative string character types by giving a dummy suffix that can be found in an aitstringtype statement. 

ijoin 

The ijoin program is a reimplementation of join(l), which handles long lines and 8-bit characters correctly. The -s switch 
specifies that the sort(l) program used to prepare the input to ijoin uses signed comparisonson 8-bit characters; the-u 
switch specifies that sort(l) uses unsigned comparisons. All other options and behaviors of join(l) are duplicated as exactly 
as possible based on the manual page, except that ijoin will not handle newline as a field separator. Seethe join(l) manual 
page for more information. 


ENVIRONMENT 

DICTIONARY 

WORDLIST 

INCLUDE_STRING 

TMPDIR 


Default dictionary to use if no -d flag is given 

Personal dictionary filename 

Code for fileinclusion under the-A option 

D irectory used for some of munchlist 'stemporary files 


FILES 

!! libdir i !/! i defhash !! H ashed dictionary (may be found in some other local directory, depending on the 

system) 

!! LIBDIR!! /!! DEFLANG !! Affix-definition fi le for munchlist 

/usr/dict/web 2 or /usr/dict/words For the Lookup function (depending on thewoRDs compilation option) 

User's private dictionary 
D irectory-specific privatedictionary 


.ispell_hashfile 
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SEE ALSO 

spell(l), egrep(l), look(l), join(l), sort(l), sq(lL), tib(lL), ispell(4L), english(4L) 

BUGS 

It takes several to many seconds for ispeii to read in the hash table, depending on size. 

When all options are enabled, ispeii may take several seconds to generate all theguessesatcorrectionsforamisspelled word; 
on slower machinesthistimeislong enough to be annoying. 

The hash table is stored as a quarter-megabyte (or larger) array, so a PDP-11 or 286 version does not seem likely, 
ispeii should understand moretrotf syntax, and deal more intelligently with contractions 

Although small personal dictionaries are sorted before they are written out, theorderof capitalizations of the same word is 
somewhat random. 

When the-xflag is specified, ispeii will unlink any existing BAK file. 

There are too many flags, and many of them havenon-mnemonic names. 

munchiist does not deal very gracefully with dictionaries that contain nonword characters. Such characters ought to be 
deleted from thedictionary with awarning message, findattix and munchiist require tremendous amounts of temporary file 
space for large dictionaries. They do respect the tmpdir environment variable so this space can be redirected. H owever, a lot 
of the temporary space needed isfor sorting, so tmpdir is only a partial help on systems with an uncooperative sort(l). 
(Cooperative is defined as accepting the undocumented -t switch). At its peak usage, munchiist takes 10 to 40 times the 
original dictionary'ssizein kilobytes. (The larger ratio isfor dictionaries that already have heavy affix use, such as the one 
distributed with ispeii). munchiist is also very slow; munching a normal-sized dictionary (15KB roots, 45KB expanded 
words) takes around an hour on a small workstation. (M ost of this time is spent in sort(l), and munchiist can run much 
faster on machines that have a more modern sort that makes better use of the memory avail able to it.) findattix is even 
worse; the smallest English dictionary cannot be processed with this script in a mere 50KB of free space, and a/en after 
specifying switches to reduce the temporary space requi red, the script will run for more than 24 hours on a small worksta¬ 
tion. 

AUTHORS 

Pace W illisson (pace@mit-vax), 1983, based on the P DP-10 assembly version. That version was written by R. E. Gorin in 
1971, and later revised by W. E. M atson (1974) and W. B. Ackerman (1978). Collected, revised, and enhanced forthe 
Usenet by Walt Buehring, 1987. T able-driven multilingual version by Geoff Kuenning, 1987-88. Large dictionaries 
provided by Bob Devine (vianetidevine). A complete list of contributors is too large to list here, but is distributed with the 
ispeii sources in thefile Ccntributors. 

VERSION 

The version of ispeii described by this manual page is International Ispeii version 3.1.00, October 8,1993. 

join 

join— Join lines of two files on a common field 

SYNOPSIS 

join [-a 112] [-v 1J2] [-e empty-string] [-0 field-list...] [-t char] 

[-j[1 ]2] field] [-1 field] [-2 field] filel fiI e2 
join {--help,--version} 

DESCRIPTION 

This manual page documents the GN U version of join, join prints to the standard output a line for each pair of input lines, 
one each from f i i e 1 and f i i e 2 , that have identical join fields. Either filename (but not both) can be-, meaning the standard 
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input, f i i ei and f i i e2 should be already sorted in increasing order (not numerically) on thejoin fields; unless the-t option 
is given, they should be sorted ignoring blanks at the start of the line, assort does when given the-b option. 

The defaults are the foil owing: The join field isthefirst field in each line; fields in the input are separated by one or more 
blanks, with leading blanks on the line ignored; fields in the output are separated by a space; each output line consists of the 
join field, the remaining fields from f i i e 1 , then the remaining fields from f i i e2. 


OPTIONS 

-a file-number 

-e string 
-1, -jl field 
-2, -j2 field 
-j field 

-o field-list... 


-t char 

-v file-number 


Print a line for each unpai rable line in file file-number (either 1 or 2), in addition to the normal 
output. 

Replace empty output fields (those that are missing in the input) with string. 

Join on field field (a positive integer) of file 1. 

Join on field field (a positive integer) of file2. 

EquivalenttO -1 field -2 field. 

Construct each output line according to theformat in fieid-iist. Each element in field-list 
consists of a file number (either 1 or 2), a period, and afield number (a positive integer). The 
elements in the list are separated by commas or blanks M ultiple field - list arguments can be 
given after a single -0 option; the values of all lists given with -0 are concatenated together. 

Use character char as the input and output field separator. 

Print a line for each unpai rable line in file file-number (either 1 or 2), instead of the normal output. 


In addition, when GNU jein is invoked with exactly one argument, the following options are recognized: 

--help Print a usage message on standard output and exit successfully. 

--version Print version information on standard output, then exit successfully. 

GNU Text Utilities 


kill 

kin— Terminate a process 

SYNOPSIS 

kill [ -s signal j -p ] [a]pid ... 
kill -1 [ signal ] 

DESCRIPTION 

kin sends the specified signal to the specified process. If no signal is specified, theTERM signal is sent. The term signal will kill 
processes that do not catch this signal. For other processes, if may be necessary to use the kill(9) signal because this signal 
cannot be caught. 

M ost modern shells have a built-in kill function. 

OPTIONS 

pid ... Specify the list of processes that kill should signal. Each pid can be a process ID, or a process name. 

-s Specify thesignal to send. The signal may be given asa signal nameornumber. 

-p Specify that kin should only print the process ID (pid) of the named process, and should not send it a signal. 

-1 Print a list of signal names. These are found in /usr/inciude/iinux/signai.h. 

SEE ALSO 

bash(l), tcsh(l), kill(2), sigvec(2) 
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AUTHOR 

T aken from BSD 4.4. The ability to translate process names to process ids was added by Salvatore Valente 
(<svalente@mit.edu>). 

L inux U till ties, 14 0 ctober 1994 


killall 

kiiiaii — Kill processes by name 

SYNOPSIS 

killall [-iv ] [-si g n a I ] name ... 
killall [-1] 

DESCRIPTION 

kiiiaii sends a signal to all processes running any of the specified commands. If no signal name is specified, sigterm issent. 

Signals can be specified either by name (for example, -hup) or by number (for example, -i). Signal 0 (check if a process exists) 
can only be specified by number. 

If the command name contains a slash (/), processes executing that particular file will be selected for killing, independent of 
their name. 

kiiiaii returns a nonzero return code if no process has been killed for any of the listed commands. If at least one process has 
been killed for each command, kiiiaii returns zero. 

A kiiiaii process never kills itself (but may kill other kiiiaii processes). 

OPTIONS 

-i Interactively ask for confirmation of killing. 

-1 List all known signal names. 

-v Report ifthesignal was successfully sent. 

FILES 

/proc Location of theproc filesystem 

KNOWN BUGS 

Killing by file only works for executables that are kept open during execution; that is, impure executables can't be killed this 
way. 

AUTHOR 

W emer Almesberger (aimesbenMi. ept 1 . ch) 

SEE ALSO 

kill(l), fuser(l), ps(l), kill(2) 

Linux, 11 October 1994 
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ksyms— Shows the exported kernel symbols 

SYNOPSIS 


ksyms [-a][-h][-m] 



last 



DESCRIPTION 

ksyms shows information about all exported kernel symbols. The format is 

address name [defining modul e ] 

The describing header can be turned off with the option -h. 

N ormally, only the symbols defined by the loaded modules are shown, but with the option -a, all exported symbols can be 
seen. 

The information can also be seen in /proc/ksyms. A shell-script version ksyms.sh can be used to get the information from / 
proc/ksyms instead, but this program gets the symbol information directly from the kernel with a system call. 

With the option -m (stands for memory map), you can also see the starting address and the size of the allocated memory for 
every loaded module. 

SEE ALSO 

insmod(l), modprobe(l), depmod(l), rmmod(l), lsmod(l), modules(2) 

HISTORY 

Theksyms command was first conceived by Bjorn Ekwall (bj0miabiox.se). The -m option wasinspired by David H inds 
(dhinds@allegro.Stanford.edu) 

BUGS 

Ksyms might have some, but they are well hidden.... 

Linux, 14 May 1995 
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last— Indicate last logins by user or terminal 

SYNOPSIS 

last [-number ] [ -f f i I e n a me ] [-t tty][-h host name ] [-i address ] [-1] [-y] [name... ] 

DESCRIPTION 

Last looks back in thewtmp file, which records all logins and logouts for information about a user, a teletype, or any group of 
users and teletypes. Arguments specify names of users or teletypes of interest. If multiple arguments are given, theinforma- 
tion that applies to any of the arguments is printed. For example last root console would list all of root'ssessionsaswell as 
all sessions on the console terminal. Last displaysthe sessions of thespecified users and teletypes, most recent first, indicating 
thetimes at which thesession began, theduration of thesession, and the teletype that the session took place on. If the 
session is still continuing or was cut short by a reboot, last so indicates. 

The pseudo-user reboot logs in at reboots of the system. 

Last with no arguments displays a record of all loginsand logouts, in reverse order. 

If last is interrupted, it indicates how far the search has progressed in wtmp. If interrupted with a quit signal, last indicates 
how far the search has progressed so far, and the search continues. 

OPTIONS 

-number Limit the number of entries displayed to that specified by number. 

-f f i i ename U se f i i e na me as the name of the accounting fi le instead of /var/iog/wtmp. 

-h hostname List Only logins from host n a me. 

-i IP address List Only logi ns from IP address. 
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-i 

-t tty 

-y 


List IP addresses of remote hosts instead of truncated hostnames. 
List only logins on tty. 

Also report year of dates. 


FILES 

/var/iog/wtmp Login database 


20 March 1992 


lbxproxy 

lbxproxy — LBX proxy server for the X Window system 

SYNOPSIS 

lbxproxy [:di spl aynumber ] [option ...] 

NOTE 

This manual page is not definitive or "official.’' It is derived from information contained in the readme file in theibx source. 

DESCRIPTION 

lbxproxy istheLow Bandwidth X pseudo-server. Itrunson the remote side of low bandwidth, high-latency connections, 
such as serial lines and wide area networks. It accepts connections from X clients at the remote end and forwards them to an 
X server at the local end. The LBX protocol used for the low bandwidth connection includes compression and optimizations 
designed to make effective use of the bandwidth available. The current version of LBX is not a standard of the X Consor¬ 
tium, and will not be compatible with the final version. The current version should be treated as an "alpha" or "prototype" 
for people interested in experimentingwith it. 

OPTIONS 

lbxproxy acceptsthefollowing options 

:di spl aynumber lbxproxy runs as the given dispiaynumber, which by default is o. A value different from 0 should be 

used if the host running lbxproxy has a local X display. If multiple lbxproxy servers or other X 
servers are to run simultaneously on a host, each must have a unique display number. (Seethe 
”D isplay N ames” section of thex(l) manual page to learn howto specify which display number 
clients should try to use.) 

-ac D isables host-based access control mechanisms Enables access by any host, and permits any host to 

modify the access control list. Use with extreme caution. Thisoption exists primarily for running 
test suites remotely. 

-display di spl ay-number Sets the name of the X server display that lbxproxy connects to. 

-help Prints a usage message. 

-i Causesall remainingcommand-lineargumentsto beignored. 

-to seconds Sets default connection time-out in seconds. 

NETWORK CONNECTIONS 

lbxproxy supports cli ent connections via most of the connection types supported bytheX servers. (Refer to the xserver(l) 
manual page and hardware-specific X server manual pages for details.) N otethat in the current implementation some of the 
connections types have not been implemented correctly. This mostly applies to System V. 
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EXAMPLES 

T o setup lbxproxy, start the X server as usual, and then start the proxy. The lbxproxy is a pseudo-server, so any clients that 
wish to use it need to adjust their display. By default, the proxy will listen on <hostname>:i. This can be changed with the 
:displaynumber argument. 

If the proxy isto be running on a host named sharedhost, connecting to an LBX-capableX server on a desktop machine 
named mydesktop, you could use the following command to start the proxy (which would be known as display sharedhost: 7 ): 

mydesktop% rlogin sharedhost 

sharedhost% lbxproxy -display mydesktop:0 :7 & 

sharedhost% xclient -display sharedhost:7 

If you are running LBX over a term connection between mydesktop and sharedhost, try something like this: 
mydesktop% trsh 

sharedhost% tredir -r 6008 6000 

sharedhost% lbxproxy -display sharedhost:8 :7 & 

sharedhost% xclient -display sharedhost:7 

SEE ALSO 

General information: x(l) 

Server-specific man pages: Xserver(l), Xdec(l), Xmacll(l), Xsun(l), Xnest(l), Xvfb(l), XF86_Accel(l), XF86_Mono(l), 

XF86_SVGA( 1), XF86_VGA1 6(1), XFree86(l) 

AUTHORS 

The LBX team includes DaveLemke, DaleT onogai, Keith Packard, Jim Fulton from N CD, and Chris Kanterjiev from 
Xerox. 

X Vera on 11 Release 6 
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id— TheGNU linker 

SYNOPSIS 

Id [ -o.I output ] .1 objfile . . . .br .RB ["-A out put ] obj fiI e ... 

[-A ar c hi t ect ur e ][-b\ i nput - f or mat ][-Bstatic ][-c\ commandf i I e ] 

[ -d J-dc|-dp ] 

[ -defsym\ symbol = expression ][-e\ entry ][-F ][-F\ format ][- 
format\ input-format ][-g ][-G size ][- - help ][-i ][-1 ar ][- 
L searchdir ][-M][-Map mapf i I e ][-m e mu I a t i on ][-n|-N][- 
noinhibit-exec ][-oformat\ out put-for mat ][-R\ filename ][-relax ] 

[ -rJ-Ur][ -S ][-s ][-sort-common][-T\ commandfile ][-Ttext\ 
textorg ][-Tdata\ dataorg ][-Tbss\ bssorg ][-t ][-u\ sym ][-V ][- 
v][--verbose ][--version ][-warn-common][-warn-once] [-X ] 

[ -x ] 

DESCRIPTION 

id combines a number of object and archive files, relocates their data, and ties up symbol references. Often the last step in 
building a new compiled program to run is a call to id. 

id accepts Linker Command Language files to provide explicit and total control over the linking process. This man page does 
not describe the command language; see the id entry in info, or the manual Ld:TheGNU Linker, for full details on the 
command language and on other aspects of theG N U linker. 
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This version of id uses the general-purpose BFD libraries to operate on object files. This allows id to read, combine; and 
write object files in many different formats, for example, COFF or a.out. D ifferent formats may be linked together to 
produce any available kind of object file You can use objdump -1 to get a list of formats supported on various architectures; 
See objdump(l). 

Aside from its flexibility, theGN U linker is more helpful than other linkers in providing diagnostic information. M any 
I inkers abandon execution immediately upon encountering an error; whenever possible id continues executing, allowing 
you to identify other errors (or, in some cases, to get an output file in spite of the error). 

TheGN U linker id is meant to cover a broad range of situations, and to be as compatible as possible with other linkers. Asa 
result, you have many choices to control its behavior through thecommand line, and through environment variables. 

OPTIONS 

T he plethora of command-lineoptionsmay seem intimidating, but in actual practice few of them areused in any particular 
context. For instance, a frequent use of id is to link standard U NIX object files on a standard, supported UNIX system. On 
such a system, this line li nks a fi le hello .0 : 

$ Id -0 output /lib/crt0.o hello .0 -lc 

This tells id to produce a file called output as the result of linking the file /lib/crte.o with heiio.o and the library nbc.a, 
which will comefrom the standard search directories. 

The command-line options to id may be specified in any order, and may be repeated at will. For the most part, repeating an 
option with a different argument will either have no further effect or override prior occurrences (those further to the left on 
thecommand line) of an option. 

The exceptions-which may meaningfully be used more than once— are -a, -b (or its synonym -format), -defsym, -l, - 1 , -r, 
and -u. 

The list of object files to be linked together, shown asobjfiie, may follow, precede, or be mixed in with command-line 
options, except that an objf iie argument may not be placed between an option flag and its argument. 

Usually the linker is invoked with at least one object file but other forms of binary input files can also be specified with - 1 , 
-r, and the script command language. If no binary input files at all are specified, the I inker does not produce any output, and 
issuesthemessageNo input files. 

0 ption arguments must either follow the option letter without intervening whitespace or be given as separate arguments 
immediately following the option that requires them. 

-Aar chi tecture In the current release of id, this option is useful only for the Intel 960 family of architec¬ 

tures. In that id configuration, the architecture argument is one of the two-letter names 
identifying members of the 960 family; the option specifies the desired output target and 
warns of any incompatible instructions in the input files. It also modifies the I inker's search 
strategy for archive libraries to support the use of Iibraries specific to each particular 
architecture, by including in the search loop names suffixed with thestring identifying the 
architecture. 

For example, if your id command lineincluded -aca as well as -itry, the linker would look 
(in its built-in search paths, and in any paths you specify with -l) for a library with the 
names 

try 

libtry.a 
tryca 

libtryca.a 

Thefirsttwo possibilities would be considered in any event; the last two are due to theuse 

of-ACA. 

Future releases of id may support similar functionality for other architecture families. 
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b i nput-format 


Bstatic 

c commandf i I e 


d, -dc, -dp 


defsym symbol = expression 


e entry 
F, -Ff or mat 


format i nput -f or mat 

g 

G si ze 
-help 


You can meaningfully use -a more than onceon a command line, if an architecture family 
allows combination of target architectures; each use will add another pair of name variants 
to search for when-l specifies a library. 

Specify the binary format for input object files that follow thisoption on thecommand line. 
You don't usually need to specify this, as id is configured to expect as a default input format 
the most usual format on each machine, i nput - f or mat is a text string, the name of a partic¬ 
ular format supported bytheBFD libraries. 

-format i nput ■ f or mat 

has the same effect, as does the script command target. 

You may want to use this option if you are linking files with an unusual binary format. You 
can also use-b to switch formats explicitly (when linking object fi les of different formats), 
by including 

-b i nput - f or mat 

before each group of object files in a particular format. 

The default format istaken from the environment variable gnutarget. You can also define 
the input format from a script, using the command target. 

This flag is accepted for command-line compatibility with theSunOS linker, but has no 
effect on id. 

D irectsid to read link commands from the file commandf iie. These commands will 
completely override id's default link format (rather than adding to it); commandfiie must 
specify everything necessary to describe the target format. 

You may also include a script of link commands directly in thecommand line by bracketing 
it between { and } characters. 

These three options are equivalent; multi pie forms are supported for compatibility with 
other linkers. U se any of them to make id assign space to common symbols even if a 
relocatable output file is specified (-r). The script command force_common_allocation has 
the same effect. 

C reate a global symbol in the output file, containing the absolute address given by 
e* pres si on. You may use this option as many times as necessary to define multi pie symbols 
in thecommand line. A limited form of arithmetic is supported for thee* pres si on in this 
context; you may give a hexadecimal constant or the name of an existing symbol, or use + 
and - to add or subtract hexadecimal constants or symbols. If you need more elaborate 
expressions, consider using the linker command language from a script. 

Use entry asthe explicit symbol for beginning execution of your program, rather than the 
default entry point. 

Some older linkers used thisoption throughout a compilation toolchain for specifying 
object-file format for both input and output object files, id's mechanisms (the -b or -format 
options for input files, the target command in linker scripts for output files, the gnutarget 
environment variable) are more flexible, but it accepts (and ignores) the -f option flag for 
compatibility with scripts written to call the old linker. 

Synonym for-b i nput-format. 

Accepted, but ignored; provided for compatibility with other tools. 

Set the maximum size of objects to be optimized using the GP register to si ze under M IPS 
EC OFF. Ignored for other object file formats. 

Print a summary of the command-line options on the standard output and exit. Thisoption 
and - -version begin with two hyphens instead of one for compatibility with other GN U 
programs. The other options start with only one hyphen for compatibility with other 
linkers. 

Perform an incremental link (same as option -r). 
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-la r 

-Lsearchdi r 


-M 

-Map mapf i I e 
-m emu I at i on 

-N 

-n 

-noinhibit-exec 

-o out put output 
-oformat out put -f or mat 


-R f i I ename file 


-relax 


-S 

-s 


-sort-common 


Add an archive file a r to the list of files to link. This option may be used any number of 
times, id will search its path list for occurrences of lib ar .afor every ar specified. 

This command adds path searchdir to the list of paths that id will search for archive 
libraries. You may use this option any number of times. 

T he default set of paths searched (without being specified with -l) depends on what 
emulation mode id is using, and in some cases also on how it was configured. The paths 
can also be specified in a link script with thesEARCH_DiR command. 

Print (to the standard output file) a link map—diagnostic in-formation about where 
symbols are mapped by id, and information on global common storage allocation. 

Print to the file mapf i i e a link map— diagnostic information about where symbols are 
mapped by id, and information on global common storage allocation. 

Emulate the emu i at i on linker. You can list the available emulations with the --verbose 
option. This option overrides the compiled-in default, which isthesystem for which you 
configured id. 

Specifies readable and writable text and data sections. If the output format supports 
UN I X-style magic numbers, the output is marked asoMAGic. 

When you use the -n option, the I inker does not page-align the data segment. 

Sets the text segment to be read-only, and nmagic iswritten if possible 
N ormally, the linker will not produce an output file if it encounters errors during the link 
process. With thisflag, you can specify that you wish theoutput file retained even after 
nonfatal errors 

output is a name for the program produced by id; if this option is not specified, the name 
a. out is used by default. The script command output can also specify the output filename. 
Specify the binary format for the output object file. You don't usually need to specify this, 
as id is configured to produce as a default output format the most usual format on each 
machine, out put-for mat is a text string, the name of a particular format supported by the 
BFD libraries. The script command output_format can also specify the output format, but 
thisoption overrides it. 

Read symbol names and their addresses from fi i ename, but do not relocate it or include it in 
theoutput. This allows your output file to refer symbolically to absolute locations of 
memory defined in other programs. 

An option with machine-dependent effects. C urrently this option is only supported on the 
H 8/300. 

On some platforms, use this option to perform global optimizations that become possible 
when the linker resolves addressing in your program, such as relaxing address modes and 
synthesizing new instructions in theoutput object file. 

On platforms where this is not supported, -relax is accepted, but has no effect. 

Generates relocatable output, that is, an output filethatcan in turn serve as input to id. 

This is often called partial linking. As a side effect, in environments that support standard 
UNIX magic numbers, thisoption also sets the output file's magic number to omagic. If this 
option is not specified, an absolute file is produced. When linking C++programs, this 
option will not resolve references to constructors; -ur is an alternative. 

This option does the same as -i. 

Omits debugger symbol information (but not all symbols) from the output file. 

Omits all symbol information from the output file 

N ormally, when id places the global common symbolsin the appropriate output sections, it 
sorts them by size. First come all the one-byte symbols, then all thetwo bytes, then all the 
four bytes, and then a/erything else. Thisisto prevent gaps between symbols dueto 
alignment constraints. Thisoption disables that sorting. 
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-Tbss org, -Tdata org, 

-Ttext org 

-T c o mma n d f i I e, -Tc o mma n d f i I e 
-t 

-u sym 


-Ur 


- -verbose 

-v, -V 

- -version 
-warn-common 


-warn-once 

-X 

-x 


Use org as the starting address for— respectively— the bss, data, or the text segment of the 
output file, textorg must be a hexadecimal integer. 

Equivalentto -c commandf i e; supported for compatibility with other tools. 

Prints names of input files as id processes them. 

Forces sym to be entered in the output file as an undefined symbol. This may, for example 
trigger linking of additional modules from standard libraries, -u may be repeated with 
different option arguments to enter additional undefined symbols. 

For anything other than C++programs, this option is equivalent to -r : it generates 
relocatable output, that is, an output file that can in turn serve as input to id. W hen linking 
C++programs, -ur will resolve references to constructors, unlike -r. 

D isplay the version number for id and list the supported emulations. Display which input 
files can and can not be opened. 

D isplay the version number for id. 

D isplay the version number for id and exit. 

Warn when a common symbol iscombined with another common symbol or with a symbol 
definition. UNIX linkers allow this somewhat sloppy practice, but linkers on some other 
operating systems do not. This option allows you to find potential problems from 
combining global symbols. 

Only warn once for each undefined symbol, rather than once per module that refers to it. 

If -s or-s is also specified, delete only local symbols beginning with l. 

If -s or -s is also specified, delete all local symbols, not just those beginning with l. 


ENVIRONMENT 

You can change the behavior of id with the environment variableGNUTARGET. 

gnutarget determines the input-fi le object format if you don't use -b (or its synonym -format). Its value should be one of the 
BFD names for an input format. If there is no gnutarget in the environment, id uses the natural format of the host. If 
gnutar-get i s set to default , then BFD attempts to discover the input format by examining binary input files; thismethod 
often succeeds, but there are potential ambiguities, sincethere is no method of ensuring that the magic number used to flag 
object-file formats is unique. However, the configuration procedure for BFD on each system places the conventional format 
for that system first in the search-list, so ambiguities are resolved in favor of convention. 


SEE ALSO 

objdump(l); id and binutiis entries in info 

Ld:TheGNU Linker, Steve Chamberlain and Roland Pesch; TheGNU B inary U tilities, Roland H. Pesch. 


COPYING 

Copyright © 1991,1992 Free Software Foundation, Inc. 

Permission isgranted to make and distribute verbatim copies of this manual provided thecopyright notice and this 
permission notice are preserved on all copies. 

Permission isgranted to copy and distribute modified versions of this manual under the conditions for verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 

Permission isgranted to copy and distribute translations of this manual into another language, under the above conditions 
for modified versions, except that this permission notice may be included in translations approved by the Free Software 
Foundation instead of in the original English. 


Cygnu support, 17 August 1992 
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lispmtopgm 

lispmtopgm— Convert a Lisp M achinebitmap file into PGM format 

SYNOPSIS 

lispmtopgm [I i spmf i I e ] 

DESCRIPTION 

lispmtopgm reads a Lisp machine bitmap as input and produces a portable graymap as output. 

Thisisthefile format written by thetv:write-bit-array-fiie function on Tl Explorer and Symbolics Lisp machines. 

M ultiplane bitmaps on Lisp machines are color; buttheiispm image file format does not include a colormap, so it must be 
treated as a graymap instead. This is unfortunate. 

SEE ALSO 

pgmtolispm(l), pgm(5) 

BUGS 

Theiispm bitmap file format is a bit quirky; Usually the image in the file has its width rounded up to the next higher 
multiple of 32, but not always. If the width is not a multiple of 32, we don't deal with it properly, but because of theiispm 
microcode, such arrays are probably not image data anyway. 

Also, theiispm code for saving bitmaps has a bug, in that if you are writing a bitmap that is not mod32 across, the file may be 
up to seven bits too short. They round down instead of up, and we don't handle this bug gracefully. 

N o color. 

AUTHOR 

Copyright® 1991 byJamieZawinski andJef Poskanzer. 

6 March 1990 


lkbib 

lkbib— Search bibliographic databases 

SYNOPSIS 

lkbib [ -v ] [ —if i e I d s ] [-pf i I e n a me ] [-tn ] key ... 

DESCRIPTION 

lkbib searches bibliographic databases for references that contain th e keys key... and prints any references found on the 
standard output, lkbib will search any databases given by -p options and then a default database. The default database is 
taken from the refer environment variable if it is set, otherwise it is 
/usr/dict/papers/Ind. 

For each database filename to be searched, if an index filename, i created by gindxbib(l) exists, then it will be searched 
instead; each index can cover multiple databases. 

OPTIONS 

-v Print the version number. 

Searchfi i ename. M ulti pie -p optionscan be used. 

When searching files for which no index exists, ignore the contents of fields whose names are in stri ng. 
Only requirethefirstn charactersof keys to be given. Initially a is 6. 


-pf i I ename 
-ist r i ng 
-tn 



In 


293 

ENVIRONMENT 

refer D efault database 

FILES 

/usr/dict/papers/ind D efault database to beused if the REFER environment variable is not set. 

filename.i IndexfileS. 

SEE ALSO 

grefer(l), glookbib(l), gindxbib(l) 

GroffVeraon 1.09, 6 August 1992 


In 

in— M ake links between files 

SYNOPSIS 

In [options] source [dest] 

In [options] source... directory 

Options: 

[-bdfinsvF] [-S backup-suffix] [-V {numbered,existing,simple}] 

[--version-control={numbered,existing,simple}] [--backup] [--directory] 
[--force] [--interactive] [--no-dereference] [--symbolic] [--verbose] 

[ --suffix=backup-suffix] [--help] [--version] 


DESCRIPTION 

This manual page documents the G N U version of in. If the last argument names an existing directory, in links each other 
given file into a file with the same name in that directory. If only one file is given, it links that file into the current directory. 
Otherwise, if only two files are given, it links the first onto the second. It is an error if the last argument is not a directory 
and more than two files are given. Itmakeshard links by default. Bydefault, it does not remove existing files. 


OPTIONS 

-b, --backup 

-d, -F, --directory 

-f, --force 

-i, --interactive 

-n, --no-dereference 


-s, --symbolic 

-v, --verbose 
--help 
--version 

-S, --suffix backup-suffix 


M ake backups of files that are about to be removed. 

Allow the superuser to make hard links to directories. 

Remove existing destination files. 

Prompt whether to remove existing destination files. 

When the specified destination is a symbolic link to a directory, attempt to replace the 
symbolic link rather than dereferencing it to create a link in the directory to which it points. 
This option is most useful in conjunction with - -force. 

M ake symbolic links instead of hard links. Thisoption produces an error message on 
systems that do not support symbolic links. 

Print the name of each file before linking it. 

Print a usage message on standard output and exit successfully. 

Print version information on standard output then exit successfully. 

The suffix used for making simple backup files can beset with thesiMPiE_BACKUP_suFFix 
environment variable, which can be overridden by thisoption. If neither of those is given, 
the default is", asitisin Emacs. 
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-v, --version-control Thetypeof backups made can beset with the versioncontrol environment variable which 

{numbered,existing,simple} can beoverridden by this option. If version_control is not set and this option is not given, 

the default backup type is existing. T he value of the version_control environment variable 
and the argument to this option are like the G N U E macs version-control variable they 
also recognize synonyms that are more descriptive. Thevalid values (unique abbreviations 
are accepted) are the following: 

t or numbered Always make numbered backups 

mi or existing Makenumbered backupsof filesthatalready havethem, simple 
backups of the others. 

never or simple Always makesimple backups 

GNU File Utilities 

lndir 

indir— Create a shadow directory of symbolic links to another directory tree 

SYNOPSIS 

lndir fromdir [todir] 

DESCRIPTION 

indir makes a shadow copy todir of a directory tree fromdir, except that the shadow is not populated with real files but 
instead with symbolic links pointing at the real files in the fromdir directory tree. This is usually useful for maintaining 
source code for different machine architectures. You create a shadow directory containing links to the real source which you 
will haveusually N FS mounted from a machine of a different architecture, and then recompile it. The object files will bein 
the shadow directory, while the source files in the shadow directory are just syml inks to the real files. 

This has the advantage that if you update the source, you need not propagate the change to the other architectures by hand 
because al I source i n shadow di rectories are symlinks to the real thing: J ust cd to the shadow di rectory and recompi Ie away. 

The todir argument is optional and defaults to the current directory. The fromdir argument may be relative (for example, 

.. / s rc) and is relative to todir (not the current directory). 

N otethat rcs, sees, and cvs.adm directories are not shad owed. 

If you add files, simply run indir again. Deleting files is a more painful problem; the syml inks will just point into never- 
neverland. 

BUGS 

patch gets upset if it cannot change the files. You should na/er run patch from a shadow directory anyway. 

You need to use something likethis: 
find todir -type 1 -print \ xargs rm 

to clear out all files before you can relink (if fromdir moved, for instance). Something likethis: 
find . \! -type d -print 

will find all files that are not directories. 
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locate 

locate— List fils in databass that match apattern 

SYNOPSIS 

locate [-d path] [ --database=path] [--version] [--help] pattern... 

DESCRIPTION 

This manual page documents the GN U version of locate. For each given pattern, locate searchsoneor more databass of 
filenamsand displays the filenams that contain the pattern. Patternscan contain shell-style meta characters: *, ?, and n. 
The metacharacters do not treat / or. specially. Therefore, a pattern too*bar can match a fi lename that contains too3/bar, 
and apattern *duck* can match afilenamethatcontainsiake/. ducky. Patterns that contain meta characters should be quoted 
to protect them from expansion by the shell. 

If a pattern is a plain string— it contains no meta characters— locate displays all filenams in the database that contain that 
string anywhere. If a pattern dos contain metacharacters, locate only displays filenams that match the pattern exactly. Asa 
rsult, patterns that contain meta characters should usually begin with a * and will most often end with one as well. The 
exceptions are patterns that are intended to explicitly match the beginning or end of afilename. 

The filename databass contain lists of filesthat were on the system when the databass were last updated. The system 
administrator can choose the filename of the default database, the frequency with which the databass are updated, and the 
directoris for which they contain entris; seeupdatedb(lL). 

OPTIONS 

-d path, --database=path 


- -help 

- -version 

ENVIRONMENT 

locate_path Colon-separated list of databassto search 

SEE ALSO 

find(lL), locatedb(5L), updatedb(lL), xargs(lL), Finding Fi les(online in info, or printed) 

logger 

logger— M ake entris in the system log 

SYNOPSIS 

logger [-is] [-f file] [-p pri] [-t tag] [message ...] 

DESCRIPTION 

logger provids a shell command interface to the sysiog(3) system log module. 


I nstead of searching the default fi lename database, search the fi lename databass in path, 
which is a colon-separated list of database filenams. You can also use the environment 
variable locatepath to set the list of databasefils to search. The option overrids the 
environment variable if both are used. 

Thefilenamedatabase format changed starting with GNU find and locate version 4.0 to 
allow machinswith different byte orderings to share thedatabass. Thisversion of locate 
can automatically recognize and read databass produced for older versionsof GN U locate 
or UN IX versionsof locate or find. 

Print a summary of theoptionsto locate and exit. 

Print the version number of locate and exit. 
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OPTIONS 

-i Log the process ID of the logger processwith each line. 

-s Log the message to standard error, as well asthesystem log. 

-ffiie Log the specified file. 

-p pr i Enter the message with the specified priority. The priority may be specified numerically or as a facility, level 
pair. For example, -p iocai3.into logsthemessage(s) as informational level in the local3 facility. The default is 
user.notice. 

-t tag M ark every line in the log with the specified tag. 

message W rite the message to log; if not specified, and the-f flag is not provided, standard input is logged. 

T he logger utility exits 0 on success, and >0 if an error occurs. 

EXAMPLE 

logger system rebooted: 

logger -p localO.notice -t HOSTIDM -f /dev/idmc 

SEE ALSO 

syslog(3), syslogd(8) 

STANDARDS 

T he logger command is expected to be compatible with IEEE Std 1003.2 (POSIX). 

BSD 4.3, 6 Junel993 

login 

login — Sign on 

SYNOPSIS 

login [ name ] 
login -p 

login -h host name 
login -f name 

DESCRIPTION 

login is used when signing on to a system. It can also be used to switch from one user to another at any time (M ost modern 
shells have support for this feature built into them, however.) 

If an argument is not given, login prompts for the username. 

If the user is not root, and if /etc/noiogin exists, the contents of this file are printed to the screen, and the login is termi¬ 
nated. This is typically used to prevent logins when the system is being taken down. 

If the user is root, then the login must be occurring on a tty listed in /etc/securetty. Failures will be logged with thesysiog 
facility. 

After these conditions are checked, the password will be requested and checked (if a password is required for this username). 
T en attempts are allowed before login dies, but after the first three, the response starts to get very slow. Login failures are 
reported via thesysiog facility. Thisfacility is also used to report any successful root logins. 

If the file .hushiogin exists, then a quiet login is performed (this disables the checking of the checking of mail and the 
printing of the last login time and message of the day). Otherwise, if /var/iog/iastiog exists, the last login time is printed 
(and the current logi n is recorded). 
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Random administrative things, such as setting the UID and GID of the tty, are performed. The term environment variable is 
preserved, if it exists; other environment variables are preserved if the -p option is used. Then the home, path, shell, term, 
mail, and logname environment variables are set. path defaults to /usr/iocai/bin:/bin:/usr/bin:. for normal users, and to / 
sbin: /bin: /usr/sbin: /usr/bin for root. Last, if this is not a quiet login, the message of the day is pri nted and the file with the 
user's name in /usr/spooi/maii will be checked, and a message printed if it has nonzero length. 

The user's shell is then started. If no shell is specified for the user in /etc/passwd, then /bin/sh is used. If there is no directory 
specified in /etc/passwd, then / is used. (The home directory is checked for the .hushiogin file described earlier.) 

OPTIONS 

-p Used by getty(8) to tell login not to destroy the environment. 

-f Used to skip a second login authentication. This specifically does not work for root, and does not appear to work 
well under Linux. 

-h Used by other servers (such asteinetd(8)) to pass the name of the remote host to login so that it may be placed in 
utmp and wtmp. Only the superuser may use this option. 

FILES 

/var/run/utmp 

/var/log/wtmp 

/var/log/lastlog 

/usr/spool/mail/* 

/etc/motd 
/etc/passwd 
/etc/nologin 
/etc/usertty 
.hushiogin 

SEE ALSO 

init(8), getty(8), mail(l), passwd(l), passwd(5), environ(7), shutdown(8) 

BUGS 

Linux, unlike other D raconian operating systems, does not check quotas. 

The undocumented BSD -r option is not supported. This may be required by somenogind(8) programs. 

AUTHOR 

Derived from BSD login 5.40 (M ay 9,1989) by M ichael Glad (giad@daimi.dk) for H P-UX Ported to Linux 0.12: Peter 
0 rbaek (poe@daimi.aau.dk). 

Linux 0.99,1 February 1993 

look 

look— D isplay lines beginning with a given string 

SYNOPSIS 

look [-dfa] [-t termchar] string [file] 

DESCRIPTION 

T he look utility displays any lines in file that contain string as a prefix. As look performs a bi nary search, the lines in file 
must be sorted. 
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If file is not specified, the file/usr/dict/words is used, only alphanumeric characters are compared, and the case of alphabetic 
characters is ignored. 

OPTIONS 

-d D ictionary character set and order; that is, only alphanumeric characters are compared. 

-f Ignore the case of alphabetic characters. 

-a U se the alternate dictionary /usr/dict/web 2 . 

-t Specify a string termination character; that is only the characters in string up to and including the first 
occurrence of termchar are compared. 

The look utility exits 0 if one or more lines were found and displayed, 1 if no lines were found, and >1 if an error occurred. 

FILES 

/usr/dict/words T he dictionary 
/usr/dict/web 2 T he alternate dictionary 

SEE ALSO 

grep(l), sort(l) 

COMPATIBILITY 

Theoriginal manual page stated that tabs and blank characters participated in comparisons when the -d option was specified. 
Thiswas incorrect and the current man page matches the historic implementation. 

HISTORY 

look appeared in version 7 AT&T U N IX. 

14Junel993 


lpq 

ipq— Spool queue examination program 

SYNOPSIS 

lpq [-1] [-P printer] [job # ...] [user ...] 

DESCRIPTION 

ipq examines the spooling area used by ipd(8) for printing files on the line printer, and reports the status of the specified jobs 
or all jobs associated with auser. ipq invoked without any arguments reportson anyjobs currently in thequeue. 

OPTIONS 

-p Specify a particular printer; otherwise the default line printer is used (or the value of the printer variable in the 
environment). All other arguments supplied are interpreted as usernames or job numbers to filter out only those 
jobs of interest. 

-1 Information about each of the files comprising the job entry is printed. N ormally, only as much information as 
will fit on one line is displayed. 

For each job submitted— in other words, each time ipr(l) is invoked— ipq reports the user's name current rank in the 
queue the names of files comprising thejob, thejob identifier (a number that may be supplied to iprm(l) for removing a 
specific job), and the total size in bytes. Job ordering is dependent on the algorithm used to scan the spooling directory and is 
supposed to be FIFO (First in First Out). Filenames comprising a job may be unavailable (when ipr(l) is used as a sink in a 
pipeline) in which case the file is indicated as(standard input). 
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If ipq warns that there is no daemon present (due to some malfunction, for example), the ipc(8) command can be used to 
restart the printer daemon. 

ENVIRONMENT 

If the following environment variable exists, it is used by ipq: 
printer Specifies an alternate default printer 

FILES 

/etc/printcap 
/var/spool/* 

/var/spool/*/cf* 

Pa/var/spool/*/lock 
/usr/share/misc/termcap 

SEE ALSO 

lpr(l), lprm(l), lpc(8), lpd(8) 

HISTORY 

ipq appeared in BSD 3. 

BUGS 

D ueto the dynamic nature of the information in the spooling directory, ipq may report unreliably. Output formatting is 
sensitive to the line length of the terminal; this can result in widely spaced columns. 

DIAGNOSTICS 

Unable to open various files. The lock file is malformed. Garbage files when there is no daemon active, but files in the 
spooling directory. 

BSD 4.2, 9 May 1991 


T o determine printer characteristics 

Thespooling directory, as determined from printcap 

Control filesspecifyingjobs 

The lock fileto obtain the currently activejob 

For manipulating the screen for repeated display 


lpr 

ipr— Offlineprint 

SYNOPSIS 

lpr [-P printer] [-# num] [-C class] [-J job] [-T title] [-U user] 

[-i [numcols]] [-1234 font] [-w num] [-cdfghlnmprstv] [name ...] 

DESCRIPTION 

ipr uses a spooling daemon to print the named files when facilities become available. If no names appear, the standard input 
is assumed. 

The following single letter options are used to notify the line printer spooler that the files are not standard text files. The 
spooling daemon will use the appropriate filters to print thedata accordingly. 

-c Thefiles are assumed to contain data produced by cifpiot(l). 

-d Thefilesareassumed to contain datafrom TeX (D VI format from Stanford). 

-f Use a filter that interprets the first character of each line as a standard FORTRAN carriage control character. 

-g Thefilesareassumed to contain standard plot data as produced by the plot routines. (See also plot for the filters 

used by the printer spooler.) 
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-i U se a filter that allows control charactersto be printed and suppresses page breaks. 

-n The files are assumed to contain data from ditroff (devi ce independent trotf). 

-p Usepr(l) to format the files (equivalent to print). 

-t Thefiles are assumed to contain data from trotf (1) (cat phototypesetter commands). 

-v The files are assumed to contain a raster i mage for devices like the B enson Varian. 

T hese options apply to the handli ng of the pri nt job: 

-p Forceoutput to a specific printer. N ormally, the default printer is used (site-dependent), or the value of the 
environment variable printer is used. 

-h Suppressthe printing of the burst page. 

-m Send mail upon completion. 

-r Remove the file upon completion of spooling or upon completion of printing (with the -s option). 

-s Use symbolic links. U sually, files are copied to the spool directory. The -s option will usesymiink(2) to link data 

files rather than trying to copy them so large files can be printed. This means the files should not be modified or 
removed until they have been printed. 

The remaining options apply to copies, the page display, and headers: 

-# num T he quantity num is the number of copies desired of each file named. For example, 

lpr -#3 foo.c bar.c more.c 

would result in three copies of the file foo.c, followed by three copies of the file bar.c, and so on. On the 
other hand, 

cat foo.c bar.c more.c | lpr -#3 

will give three copies of the concatenation of thefiles. Often a site will disable this feature to encourage use 
of a photocopier instead. 

1234 font Specifies a font to be mounted on font position i . The daemon will construct a .raiimag file referencing 

thefont pathname. 

-c Ar class J ob classification to use on the burst page. For example 

lpr -C EECS foo.c 

causes the system name—the name returned by hostname(l)— to be replaced on the burst page by EECS, 
and the file foo.c to be printed. 

-j Ar job Job nameto print on the burst page. N ormally, the first file's name is used. 

-t Ar title Titlenameforpr(l), instead of thefilename. 

-u user Username to print on the burst page, also for accounting purposes. This option is only honored if the real 

user ID isdaemon (or that specified in the printcap file instead of daemon), and isintended for those 
instances where print filters wish to requeuejobs. 

-i numcois The output is indented. If the next argument is numeric numcois, it is used as the number of blanks to be 
printed before each line; otherwise, eight characters are printed. 

-w ns Ar num U ses num asthe page width for pr(l). 

ENVIRONMENT 

If the following environment variable exists, it is used by ipr: 
printer Specifies an alternate default printer 

FILES 

etc/passwd Personal identification. 

/etc/printcap Printer capabilities database. 

/usr/sbin/ipd* Line printer daemons. 

/var/spooi/output/* D irectories used for spooling. 
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/ var/spool/out put/*/cf* Daemon control files. 

/ var / spool/out put /*/df* D ata files specified in of files. 

/var/spooi/output/*/tf* Temporary copiesof of files. 

SEE ALSO 

lpq(l), lprm(l), pr(l), symlink(2), printcap(5), lpc(8), lpd(8) 

HISTORY 

Theipr command appeared in BSD 3. 

DIAGNOSTICS 

If you try to spool too large a file it will be truncated, ipr will object to printing binary files. If a user other than root prints a 
file and spooling is disabled, ipr will print a message saying so and will not put jobs in the queue. If a connection toipd(l) 
on the local machine cannot be made, ipr will say that the daemon cannot be started. D iagnosticsmay be printed in the 
daemon's log file regarding missing spool files by ipd(l). 

BUGS 

Fonts for troff(l) and T eX reside on the host with the printer. It is currently not possible to use local font libraries. 

BSD 4, 24 July 1991 

Iprm 

iprm — Removejobsfrom the line printer spooling queue 

SYNOPSIS 

Iprm [-P printer] [■ job # ...] [user ...] 

DESCRIPTION 

iprm will remove a job, or jobs, from a printer's spool queue. Since the spooling directory is protected from users, using iprm 
is normally the only method by which a user may remove a job. The owner of a job is determined by the user's login name 
and hostnameon the machine where theipr(l) command wasinvoked. 

Options and arguments: 

-p printer Specify the queue associated with a specific printer; otherwise, the default printer is used. 

If a single - is given, iprm will remove all jobs that a user owns. If the superuser employs thisflag, the spool 
queue will be emptied entirely. 

user Causes iprm to attempt to remove any jobs queued belonging to that user (or users). This form of invoking 

iprm is useful only to the superuser. 

job # A user may dequeue an individual job by specifying its job number. This number may be obtained from 

the ipq(l) program. For example 

lpq - -1 

1st:ken [job#013ucbarpa] 

(standard input) 100 bytes 

Iprm 13 

If neither arguments nor options are given, iprm will delete the currently activejob if it is owned by the user who invoked 
Iprm. 

iprm announces the names of any files it removes and is silent if there are no jobs in the queue that match the request list. 

iprm will kill off an active daemon, if necessary, before removing any spoolingfiles. If a daemon is ki lied, a new oneis 
automatically restarted upon completion of file removals. 
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ENVIRONMENT 

If the following environment variable exists, it is utilized by iprm: 

printer If the environment variable printer exists, and aprinter has not been specified with the -p option, the default 
printer is assumed from printer. 

FILES 

/etc/prmtcap Printer ch aracteri sti cs f i I e 

/var/spooi/* Spooling directories 

/var/spooi/*/iock Lock file used to obtain the pid of the current daemon and thejob number of the currently active 
job 

SEE ALSO 

lpr(l), lpq(l), lpd(8) 

DIAGNOSTICS 

"Permission denied” if the user tries to removefiles other than hisown. 

BUGS 

Because there are race conditions possible in the update of the lock file, the currently active job may be incorrectly identified. 

HISTORY 

T he iprm command appeared in BSD 3.0. 

BSD 4.2, 9 May 1991 

lptest 

lptest— Generate line printer ripple pattern 

SYNOPSIS 

lptest [length] [count] 

DESCRIPTION 

lptest writes the traditional "ripple test" pattern on standard output. In 96 lines, this pattern will print all 96 printable 
ASCII characters in each position. Although originally created to test printers, it is quite useful for testing terminals, driving 
terminal ports for debugging purposes, or any other task where a quick supply of random data is needed. 

T he length argument specifies the outputline length if the default length of 79 isinappropriate. 

The count argument specifies the number of output lines to be generated if the default count of 200 isinappropriate. N ote 
that if count isto be specified, length must also be specified. 

HISTORY 

lptest appeared in BSD 4.3. 



BSD 4.3, 9 May 1991 
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Is, dir, vdir 

is, dir, vdir— List contents of directories 

SYNOPSIS 

Is [-abcdfgiklmnpqrstuxABCFGLNQRSUXI] [-wools] [-T cols] [-1 pattern] [--all] 
[--escape] [--directory] [--inode] [--kilobytes] [- - numeric-uid-gid] [-no-group] 
[--hide-control-chars] [--reverse] [--size] [--width=cols] [--tabsize=cols] 

[--almost-all] [--ignore-backups] [--classify] [--file-type] [--full-time] 

[--ignore=pattern] [--dereference] [--literal] [--quote-name] [--recursive] 

[-- -sort={none, time, size, extension}] [--format={long, verbose, commas, 
across, vertical, single-column}] [--time={atime, access, use, ctime, status}] 
[--help] [--version] [name...] 


DESCRIPTION 

This manual page documents the G N U version of is. dir and vdir are versions of is with different default output formats. 
These programs list each given file or directory name. D i rectory contents are sorted alphabetically. For is, files are by default 
listed in columns, sorted vertically, if the standard output is a terminal; otherwise, they are listed one per line. For dir, files 
are by default listed in columns, sorted vertically. For vdir, files are by default listed in long format. 


OPTIONS 

-a, - -all 
-b, --escape 

-c, - -time=ctime, 
--time=status 

-d, --directory 
-f 

--full-time 


-i, - -inode 
-k, - -kilobytes 

-1, - -format=long, 
- -format=verbose 


-m, - -format=commas 
-n, --numeric-uid-gid 
-P 

-q, --hide-control-chars 
-r, - -reverse 
-s, --size 


-t, --sort=time 


-u, --time=atime, 

--time=access,--time=use 


List all filesin directories, including all files that start with aperiod (.). 

Quote nongraphic characters in filenames using alphabetic and octal backslash sequences 
like those used in C. 

Sort directory contents according to the files' status change time instead of the modification 
time. If the long listing format is being used, pri nt the status change time instead of the 
modification time 

List directories like other files, rather than listing their contents 

Do not sort directory contents; list them in whatever order they are stored on the disk. This 

isthesameasenabling -a and -u and disabling - 1 , -s, and -t. 

List times in full, rather than using the standard abbreviation heuristics. 

Ignored; for U NIX compatibility. 

Print the index number of each file to the left of the filename. 

If file sizes are being listed, print them in kilobytes. This overrides the environment variable 

POSIXLY_CORRECT. 

In addition to the name of each file, print the file type permissions, number of hard links 
owner name, group name size in bytes, and timestamp (the modification time unless other 
times are selected). For files with a time that is more than six months old or more than one 
hour into the future the timestamp contains the year instead of the time of day. 

List files horizontally, with as many as will fit on each line separated by commas. 
Listthenumeric U ID andGID instead of the names. 

Append a character to each filename indicating thefile type 
Print question marks instead of nongraphic characters in filenames. 

Sort directory contents in reverse order. 

Print the size of each filein 1KB blocks to the left of the filename. If the environment 
variable posixly_correct is set, 512-byte blocks are used instead. 

Sort directory con tents by timestamp instead of alphabetically, with the newest files listed 
first. 

Sort directory contents according to the files' last access time instead of the modification 
time. If the long listing format is being used, print the last access time instead of the 
modification time 
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-x, --format=across, 

- -format=horizontal 
-A, --almost-all 
-B, --ignore-backups 
-C, --format=vertical 
-F, - -classify 

-G, --no-group 
-L, - -dereference 
-N, --literal 
-Q, --quote-name 
-R, - -recursive 
-S, --sort=size 
-U, - -sort=none 


-X, --sort=extension 

-1, --format=single-column 
-w, --width cols 


-T, --tabsize cols 
-I, --ignore pattern 


--help 
--version 


List the files i n columns, sorted horizontally. 

List all files in directories, except for'.' and 

Do not I ist files that end with ', unless they are given on thecommand line. 

List files in columns, sorted vertically. 

Append a character to each filename indicating the file type For regular files that are 
executable, append a *. The file type indicators are / for directories, @ for symbolic links ! 
for FIFOs, = for sockets, and nothing for regular files. 

Inhibit display of group information in a long format directory listing. 

List thefiles linked to by symbolic links instead of listing the contents of the links. 

Do not quote filenames. 

Enclose filenames in double quotes and quote nongraphic characters asin C. 

List the contents of all directories recursively. 

Sort directory contents by file size instead of alphabetically, with the largest files listed first. 
Do not sort directory contents; list them in whatever order they are stored on the disk. This 
option is not called -t because the U l\l IX is -f option also enables -a and disables - 1 ,-s, 
and -t. It seems useless and ugly to group those unrelated things together in one option. 
Because this option doesn't do that, it has a different name. 

Sort directory contents alphabetically by file extension (characters after the last period); files 
with no extension are sorted first. 

List onefile per line 

Assume the screen iscois columnswide. The default istaken from the terminal driver if 
possible otherwise, the environment variable columns isused if it is set; otherwise, the 
default is 80 . 

Assume that each tab stop iscois columnswide. The default is 8. 

Do notlistfileswhosenames match the shel I pattern pattern unless they are given on the 
command line. Asin the shell, an initial period (.) in a filename does not match a wildcard 
at the Start Of pattern. 

Print a usage message on standard output and exit successfully. 

Print version information on standard output then exit successfully. 


BUGS 

On BSD systems the-s option reports sizes that are half the correct values for files that are N F S-mounted from FI P-UX 
systems. On HP-UX systems it reports sizes that are twice thecorrect values forfiles that areN FS-mounted from BSD 
systems. This is due to a flaw in H P-UX; it also affects the H P-UX is program. 

GNU File Utilities 


lsattr 

isatti — List file attributes on a Linux second extended filesystem 

SYNOPSIS 

lsattr [ -Radv ] [ files... ] 

DESCRIPTION 

lsattr lists thefiles attributes on an second extended filesystem. 
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OPTIONS 

-R Recursively list attributes of di rectories and their contents. 

-a List all filesin directories, including filesthat start with period (.). 

-d List directories like other files, ratherthan listing their contents 
-v List the files version. 

AUTHOR 

isattr has been written by Remy Card (card@masi. ibp.tr), thedeveloper and maintainer of the ext 2 fs. 

BUGS 

There are none:-). 

AVAILABILITY 

Isattr is available for anonymous FT P from ftp.ibp.fr and tsx- 11 .mit. edu in /pub/linux/packages/ext 2 f s. 

SEE ALSO 

chattr(l) 

Version 0.5b, N ov&nberl994 


Ismod 

ismod— show the loaded modules 

SYNOPSIS 

Ismod 

DESCRIPTION 

ismod shows information about all loaded modules. The format is 

na me size [list of referring mo d u I es ] 
size isin4Kb pages. 

T his information is a copy of the contents of /proc/moduies. 

SEE ALSO 

insmod(l), modprobe(l), depmod(l), rmmod(l), ksyms(l), modules(2) 

HISTORY 

The module support was first conceived by Anonymous (as far as I know...). Linux version by BasLaarhoven 
(bas@vimec.ni), 0.99.14 version byjon T ombs(jon@gtex 02 .us.es), extended by Bjorn Ekwall (bj 0 m@biox.se). 

BUGS 

ismod might have some, but they are well hidden.... 


Linux, 14 May 1995 
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lynx 

lynx— A general-purpose distributed information browser for the World Wide Web 

SYNOPSIS 

lynx [options] [pat h or URL ] 

Use lynx -help to display a complete list of current options. 


DESCRIPTION 

lynx is a fully-featured World Wide Web (WWW) client for users running cursor-addressable, character-cell display devices 
(for example, vtlOO terminals, vtlOO emulators running on PCs or M acs, or any other "curses-oriented" display). I twill 
display H ypertext M arkup Language (HTM L) documents containing links to files residing on the local system, as well as 
files residing on remote systems running Gopher, HTTP, FTP, WAIS, and N NTP servers. Current versions of lynx run on 
UN IX and VMS. 

lynx can be used to access information on the World Wide Web, or to build information systems intended primarily for 
local access. For example, lynx has been used to build several Campus Wide Information Systems (CW IS). In addition, lynx 
can beused to build systems isolated within a single LAN . 


OPTIONS 


At startup, lynx will load any local file or remote URL specified at the command line. For help with U RLs, press? or h while 
running lynx. Then follow the link titled "H el p on URLs." 


-anonymous 

-ascii 

-auth=l D: PASSWD 
-book 

-buried news 


-cache=N UMBER 
-case 

-cfg=FI LENAME 

-child 

-crawl 

-display=DI SPLAY 
-dump 

-editor=EDITOR 

-emacskeys 

-enable_scrollback 

-error_file=FI LE 
-euc 

-fileversions 
-force html 


If the only argument is -, then lynx expects to receive the arguments from stdin.Thisisto allow 
for the potentially very long command line that can be associated with the -getjata or -postjata 
arguments. (See entries for each later in this list.) 

U sed to specify the anonymous account. 

D isable kanji code translation when J apanese mode is on. 

Set authorization ID and password for protected documents at startup. 

Use the bookmark page as th e startf i I e. The default or command line startfile is still set for the 
M ain screen command, and will beused if the bookmark page is unavailable or blank. 

T oggles scanning of news articles for buried references, and converts them to newslinks N ot 
recommended because e-mail addresses enclosed in angle brackets will be converted to false news 
links, and uuencoded messages can be trashed. 

Set the number of documents cached in memory. The default is 10 . 

Enable case-sensitive string searching. 

Specifies a lynx configuration file other than the default lynx.ctg. 

Exit on left-arrow in startfile, and disable save to disk. 

With -traversal, output each page to a file. With -dump, format output as with -traversal, but to 
stdout. 

Set the display variable for X rexeced programs. 

D umps the formatted output of the default document or one specified on the command line to 
standard out. Thiscan beused in the following way: lynx -dump http://www.w3.org/defauit.htmi. 
Enable Edit mode using the specified editor (vi, ed, emacs, and so on). 

Enable Emacs-like key movement. 

Togglecompatibility with comm programs' scrollback keys(may beincompatiblewith some 
packages). 

Define a file where lynx will report HTTP access codes. 

Set kanji code to EU C when Japanese mode is on. 

I nclude al I versions of files in local VM S directory listings. 

Forces thefirst document to be interpreted asHTM L. 



-ftp 

-get_data 

-head 

-help 

-historical 

-homepage=URL 

-image_links 

-index=URL 

-jpn 

-link=U MB E R 

-localhost 

-locexec 

-mime_header 

-minimal 

-nobrowse 

-noexec 

-nolist 

-nolog 

-noprint 

-noredir 

-nostatus 

-number_links 

-post_data 

-print 

-pseudo_inlines 

-realm 

-reload 

-restrictions^ option] 
[.option][.option]... 


lynx 



Disable FTP access. 

Send form data from stdin usi ng get method and dump results. 

Send a head request for the mi me headers. 

Print this lynx command syntax usage message. 

T oggles use of > or -> as a termi nator for comments. 

Set home page separate from start page. 

Toggles inclusion of links for all images. 

Set the default index file to the specified URL. 

T oggles Japanese character translations on or off. 

Starting count for ink#.dat files produced by -crawl. 

D isable U RLsthat point to remote hosts. 

Enable local program execution from local files only (if lynx was compiled with local execution 
enabled). 

Prints theMiME header of a fetched document alongwith its source. 

T oggles minimal versus valid comment parsing. 

D isable directory browsing. 

Disable local program execution (default). 

D isable the link list feature in dumps. 

D isable mai ling of error messages to document owners. 

Disable print functions. 

Prevents automatic redirection and printsa messagewith a link to the new URL. 

D isable the retrieval status messages. 

Force numbering of links 

Send form data from stdin usi ng post method and dump results. 

Enable print functions (default). 

T oggles pseudo-ALTsfor inlines with no alt string. 

Restricts access to U RLsin the starting realm. 

Flushes the cache on a proxy server (only the first document affected). 

Allows a list of services to be disabled selectively. The following list is printed if no options are 
specified. 

an— Restricts all options. 

bookmark--D isallow changing the location of the bookmark file. 
bookmark_exec-D isallow execution links via the bookmark file. 

change_exec_perms — D isallow changing the execute permission on files (but still allow it for 
directories) when local file management is enabled. 

default --Same as command-line option -anonymous. D isables default services for anonymous users. 
Currently set to all restricted except for the following: inside_telnet, outside_telnet, inside_news, 
inside_ftp, outside_ftp, inside_rlogin, outside_rlogin, jump, mail, and goto. D efaultS are Settable 
within userdefs.h. 

dired_support — D isallow local file management. 

disk_save — D isallow saving binary files to disk in thedownload menu. 

downioad--D isallow downloadersin thedownload menu. 

editor— D isallow editing. 

exec--D isable execution scripts 

exec_frozen--D isallow theuser from changing the local execution option. 
fiie_uri—D isallow using goto to go to file: U RLs. 
goto— D isable the g (goto) command. 
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-rlogin 

-selective 

-show_cursor 


-sjis 

-source 

-telnet 

-term=TERM 


-trace 

-traversal 


-underscore 

-validate 

-version 

-vikeys 


inside_ftp — D isallow FT Ps for peoplecoming from inside your domain, (utmp required for 
selectivity.) 

inside_news — D isallow U senet news posting for people coming from inside your domain, (utmp 
required for selectivity.) 

inside_riogin — D isallow rlogins for people coming from inside your domain, (utmp required for 
selectivity.) 

inside_teinet-D isallow Tel nets for people coming from inside your domain, (utmp required for 
selectivity.) 

jump— D isablethe j (jump) command. 
maii--D isable mailing feature 
news_post--D isable U senet news posting. 
options_save--D isallow Saving options in . lynxrc. 

outside_ttp — D isallow FTPs for people coming from outside your domain, (utmp required for 
selectivity.) 

outside_news — D isallow Usenet news posting for people coming from outside your domain, (utmp 
required for selectivity.) 

outside_riogin — D isallow rloginsfor people coming from outsideyour domain, (utmp required for 
selectivity.) 

outside_teinet— D isallow Tel nets for people coming from outsideyour domain, (utmp required for 
selectivity.) 

print— D isallow most print options, 
shell— D isallow shell escapes and lynxexec or lynxprog goto's. 
suspend --D isallow UNIX Ctrl+Z suspends with escape to shell. 
teinet_port— D isallow specifying a port in Telnet goto's. 

D isable recognition of rlogin commands. 

Require .wwwbrowsablefilesto browse directories. 

If enabled, thecursor will not be hidden in theright-hand corner but will instead be positioned at 
the start of the currently selected link. show_cursor is the default for systems without fancy_curses 
capabilities, and the default configuration can be changed in userdefs.h. 

Set kanji code to ShiftJISwhenJapanesemodeison. 

Works the same as dump but outputs HTM L source instead of formatted text. 

D isable recognition of Telnet commands. 

T ell lynx what terminal type to assume it’s talking to. (This may be useful for remote execution 
when, for example, lynx connects to a remote TCP/IP port that starts a script that, in turn, starts 
another lynx process.) 

T urns on WWW trace mode. 

T raverse al I HTTP links derived from startfiie. When used with -crawl, each link that begins 
with the same string as startfiie isoutputto afile, intended forindexing. See crawl, announce for 
moreinformation. 

TOggleSUSeof underline_format in dumps. 

Accept only HTTP U RLs (for validation). Complete security restrictions also are implemented. 
Print version information. 

E nable vi-like key movement. 


COMMANDS 

■ U se U p arrow and D own arrow to scroll through hypertext links 

■ Right arrow or Return will follow a highlighted hypertext link. 

■ Left Arrow will retreat from a link. 
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■ Type h or ? for online help and descriptions of keystroke commands. 

■ Type k for a complete list of the current keystroke command mappings. 


NOTES 

T his is the Lynx 2.5 Release for U N *X/V M S. 

If you wish to contribute to the further development of lynx, subscribe to our mailing list. Send e-mail to majordomo@sig.net 
with "subscribe lynx-dev" astheonly linein the body of your message. 

Send bug reports, comments, and suggestions to iynx-dev@sig.net after subscribing. 

Unsubscribe by sending e-mail to majordomo@sig.net with unsubscribe lynx-dev as the only line in the body of your message. 
Do not send the unsubscribe message to theiynx-dev list itself. 

ACKNOWLEDGMENTS 

lynx has incorporated code from a variety of sources along the way. The earliest versions of lynx included code from Earl 
Fogel of Computing Services at the University of Saskatchewan, who implemented hyperrez in the UN *X environment. 
hyperrez was developed by N id Larson ofihink.com and served as the model for the early versions of lynx. Those versions 
also incorporated libraries from theU N*X Gopher clients developed at the U niversity of M innesota, and the later versions of 
lynx rely on theWW W client library code developed by Tim Berners-Lee and theWW W community. Also a special thanks 
to FoteosM acrides, who ported much of lynx to VM S and to everyone on theN et who has contributed to lynx's develop¬ 
ment either directly (through comments or bug reports) or indirectly (through inspiration and development of other 
systems). 

AUTHORS 

Lou M ontulli, Garrett Blythe, Craig Lavender, M ichael Grobe, Charles Rezac 
Academic Computing Services 
University of Kansas 
Lawrence, Kansas66047 

Foteos M acrides 
Worcester Foundation 
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macptopbm 

macptopbm— C onvert a M acPaint file into a portable bitmap 

SYNOPSIS 

macptopbm [-extraskip N][macpf i I e] 

DESCRIPTION 

macptopbm reads a M acPaint file as input and produces a portable bitmap as output. 

OPTIONS 

-extraskip This flag is to get around a problem with some methods of transferring files from the M ac world to the 

UNIX world. M ost of these methods leave the M ac files alone, but a few of them add thetind-erinfo data 
onto the front of the U NIX file. This means an extra 128 bytes to skip over when reading the file. The 
symptom to watch for is that the resulting PBM file looks shifted to one side. If you get this, try - 
extraskip 128 , and if that still doesn't look right, try another value. 


All flags can be abbreviated to their shortest unique prefix. 
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SEE ALSO 

picttoppm(l), pbmtomacp(l), pbm(5) 

AUTHOR 

Copyright © 1988 by Jef Poskanzer. T heM acPaint-reading code is copyright© 1987 by PatrickJ. N aughton 
(naughton@wind.sun.com). 

29 March 1989 
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make— GN U make utility to maintain groups of programs 

SYNOPSIS 

make [ -f makefile ] [ option ] ... target ... 

WARNING 

This man page is an extract of the documentation of GN U make. It is updated only occasionally because the G N U project 
does not usenroft. For complete, current documentation, refer to the into file make or the D VI filemake.dvi, which are 
made from the texinfo source fi le make, t exinfo. 

DESCRIPTION 

The purpose of the make utility isto determine automatically which pieces of a large program need to be recompiled, and 
issue the commands to recompilethem. Thismanual page describes the GN U implementation of make, which was written by 
Richard Stallman and Roland M cGrath. Our examples show C programs because they are most common, but you can use 
make with any programming language whose compiler can be run with a shell command. In fact, make is not limited to 
programs. You can use it to describe any task where some files must be updated automatically from others whenever the 
others change. 

T o prepare to use make, you must write a file called the makefile that describes the relationships among files in your program 
and states the commands for updating each file In a program, typically, the executable file is updated from object files, 
which are in turn made by compiling source files. 

0 ncea suitable makefi le exists, each timeyou change some source files, thissimple shell command: 
make 

suffices to perform all necessary recompilations The make program uses the makefile database and the last-modification times 
ofthefilesto decide which of the files need to beupdated. For each of those files, it issues the commands recorded in the 
database. 

make executes commands in the makefile to update one or more target names, where name is typically a program. If no -f 
option is present, make will look for the makefiles GNu-makefiie, makefile, and Makefile, in that order. 

N ormally you should call your makefile either makefile or Makefile. (We recommend Makefile because it appears promi¬ 
nently near the beginning of a directory listing, right near other important files such as readme.) T he first name checked, 
GNUmakefiie, is not recommended for most makefiles. You should use this name if you have a makefile that is specific to 
GNU make, and will not be understood by other versions of make. If makefile is-, the standard input is read. 

make updates a target if it depends on prerequisite files that have been modified si nee the target was last modified, or if the 
target does not exist. 
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OPTIONS 

-b, -m These options are ignored for compatibility with other versions of make. 

-c di r Change to directory d i r before reading the makefiles or doing anything else. If multi pie-c options are specified, 
each is interpreted relative to the previous one:-c / -c etc is equivalent to-c /etc. This istypically used with 
recursive invocations of make. 

-d Print debugging information in addition to normal processing. The debugging information says which files are 
being considered for remaking, which file times are being compared and with what results, which files actually 
need to be remade, which implicit rules are considered and which are applied— everything interesting about how 
make decides what to do. 

-e Give variables taken from the environment precedence over variables from makefiles. 

-f f i i e Usem e as a makefile 

-i Ignore all errors in commands executed to remakefiles. 

-i dir Specifies a directory d i r to search for included makefiles. If several -i options are used to specify several directo¬ 
ries, the directories are searched in the order specified. Uni ike the arguments to other flags of make, directories 
given with -i flags may come directly after the flag: -id i r is allowed, as well as-i di r .This syntax is allowed for 
compatibility with theC preprocessor's-i flag. 

-j jobs Specifies the number of jobs (commands) to run simultaneously. If there is more than one-j option, the last one 
is effective. If the- j option is given without an argument, make will not limit the number of jobs that can run 
simultaneously. 

-k Continue as much as possible after an error. Although the target that failed, and those that depend on it, cannot 
be remade, theother dependencies of these targets can be processed all thesame. 

-l, Specifies that no new jobs (commands) should be started if there are other jobs running and the load average is at 
-l load I east load (a floating-point number). With no argument, removes a previous load limit. 

-n Print the commands that would beexecuted, but do not execute them. 

-o f i i e Do not remake the file file even if it is older than its dependencies, and do not remake anything because of 
changes in f i i e. Essentially, the file is treated as very old and its rules are ignored. 

-p Print the database (rules and variable values) that results from reading the makefiles; then execute as usual or as 
otherwise specified. This also prints the version information given by the -v switch (see below). T o print the 
database without trying to remake any files, usemake -p -f/dev/nuii. 

-q Question mode. Do not run any commands or print anything; just return an exit status that is zero if the specified 
targets are already up-to-date, nonzero otherwise. 

-r Eliminate use of the built-in implicit rules. Also clear out the default list of suffixes for suffix rules. 

-s Silent operation; do not print the commands asthey are executed. 

-s Cancel the effect of the -k option. This is never necessary except in a recursive make where -k might be inherited 
from the top-level makeviaMAKEFLAGs or if you set -k in makeflags in your environment. 

-t Touch files (mark them up-to-date without really changi ng them) instead of runningtheircommands.Thisis 
used to pretend that the commands were done, in order to fool future invocations of make. 

-v Print the version of the make program plus a copyright, a list of authors, and a noticethatthereisno warranty. 

After this information is printed, processing continues normally. T o get this information without doing anything 
else, use make -v -f/dev/nuii. 

-w Print a message containing the working directory before and after other processing. This may be useful for 
tracking down errors from complicated nests of recursive make commands. 

-w me Pretend that the target file hasjust been modified. W hen used with the-n flag, thisshowsyou whatwould 
happen if you were to modify that file. Without -n, it is almost the same as running a touch command on the 
given file before running make, except that the modification time is changed only in the imagination of make. 

SEE ALSO 

/usr/local/doc/gnumake.dvi 

TheGNU M akeM anual 
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BUGS 

See the chapter "Problems and Bugs" InTheGNU Make Manual. 

AUTHOR 

This manual page contributed by Dennis M orseof Stanford University. It has been reworked by Roland M cGrath. 

GNU, 22 August 1989 
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makedepend— C reate dependencies in makefiles 

SYNOPSIS 

makedepend [ -Dname=def ][-Dname ][-Iincludedin ][-Yincludedir ][-a ] 

[-fmakefile ][-oobjsuffix ][-pobjprefix ][-sstring ][-wwidth ][-v ][-m ] 

[--otheroptions -- ] sourcefile . . . 

DESCRIPTION 

makedepend reads each s our c ef i e in sequence and parses it like a C-preprocessor, processing all #inciude, #define, #undef, 
#ifdef, #it ndef, #endit, #it and #eise directives so that it can correctly tell which #inciude, directives would be used in a 
compilation. Any #inciude, directives can reference files having other #inciude directives, and parsing will occurin these files 
as well. 

Every file that a sourcefile includes, directly or indirectly, is what makedepend cal Is a dependency. These dependencies are then 
written to a makefile in such away that make(l) will know which object files must be recompiled when a dependency has 
changed. 

By default, makedepend places its output in thefile named makefile if it exists; otherwise, Makefile. An alternate makefile may 
be specified with the-f option. It first searches the makefile for the line 

# DO NOT DELETE THIS LINE — make depend depends on it. 

or one provided with the-s option, as a delimiter for the dependency output. If it finds it, it will delete everything following 
this to the end of the makefile and put the output after this line. If it doesn't find it, the program will append the string to 
the end of the makefile and place the output following that. For each sourcefile appearing on the command line, makedepend 
puts lines in the makefile of theform: 
sourcefile.o: dfile . . . 

where sourcefile. o is the name from the command line with its suffix replaced with .o, and dfiie is a dependency 
discovered in a#inciude directivewhileparsingsourcef i e oroneof thefilesit included. 

EXAMPLE 

N ormally, makedepend will be used in a makefile target so that typing makedepend will bring the dependencies up-to-date for 
the makefile. For example 

SRCS = filel.c file2.c . . . 

CFLAGS = -0 -DHACK -I../foobar -xyz 
depend: 

makedepend -- $(CFLAGS) -- $(SRCS) 

OPTIONS 

makedepend will ignore any option that it does not understand so that you may use the same arguments that you would for 
cc(1). 

-Dname=def or D efi ne. This places a definition for name in makedepend's symbol table. Without =def, the symbol becomes 
-Dname defined asi. 



makedepend 



-Iincludedir 

-Yincludedir 

-a 

-fmakefile 
-oobjsuffix 

-pobjprefix 

-sstring 

-wwidth 

-v 

-m 


— options — 


Include directory. This option tel Is makedepend to prepend mciudedir to its list of di rectories to search 
when it encounters a #inciude directive. By default, makedepend only searches the standard include 
directories (usually /usr/inciude and possibly a compiler-dependent directory). 

Replace all of thestandard include directories with the single specified i nclude directory; you can omit the 
inciudedir to si mply prevent searching the standard include directories. 

Append the dependencies to the end of the file instead of replacing them. 

Filename. T his allows you to specify an alternate makefile in which makedepend can place itsoutput. 

Object file suffix. Some systems may have object files whose suffix is something other than . 0 . This option 
allows you to specify another suffix, such as .b with -o.b or :obj with -0 : obj and so forth. 

Object file prefix. The prefix is prepended to the name of the object file. This is usually used to designate a 
different directory for the object file. T he default is the empty string. 

Starting string delimiter. This option permits you to specify a different string for makedepend to look for in 
the makefile. 

Line width. N ormally, makedepend will ensure that every output line that it writes will be no wider than 78 
characters for the sake of readability. Thisoption enables you to change thiswidth. 

Verbose operation. This option causes makedepend to emit the list of files included by each input file on 
standard output. 

Warn about multiple inclusion. Thisoption causes makedepend to produce a warning if any input file 
includes another file more than once. In previous versions of makedepend, this was the default behavior; the 
default has been changed to better match the behavior of theC compiler, which does not consider 
multiple inclusion to bean error. Thisoption is provided for backwards compatibility, and to aid in 
debugging problems related to multiple inclusion. 

If makedepend encounters a double hyphen (—) in the argument list, then any unrecognized argument 
following it will be silently ignored; a second double hyphen terminates this special treatment. In this way, 
makedepend can bemadeto safely ignore esoteric compiler arguments that might normally be found in a 
cflags make macro. (See the preceding "Example'' section.) All options that makedepend recognizes and that 
appear between the pair of double hyphens are processed normally. 


ALGORITHM 

T he approach used in this program enables it to run an order of magnitude faster than any other dependency generator I 
have ever seen. Central to this performance are two assumptions: that all files compiled by a single makefile will be compiled 
with roughly the same -1 and -d options; and that most files in a single directory will include largely the same files. 

Given these assumptions, makedepend expects to be called once for each makefile with all source files that are maintained by 
the makefile appearing on the command line It parses each source and include file exactly once maintaining an internal 
symbol table for each. Thus, the first file on the command line will take an amount of time proportional to the amount of 
time that a normal C preprocessor takes. But on subsequent files, if it encounters an include filethat it has already parsed, it 
does not parse it again. 

For example, imagineyou are compiling two files, fiiei.c and fiie 2 .c; they both include the header file header, h, and the 
file header, h in turn includes the files def 1 .h and def 2 .h. W hen you run the command: 
makedepend fiiei.c file2.c 

makedepend will parse fiiei .c and consequently, header, h and then det 1 . h and def 2 .h. It then decides that the dependencies 
forthisfileare 

filel.o: header.h defl.h def2.h 

But when the program parses tiie 2 .c and discovers that it, too, includes header, h, it does not parse thefile, but simply adds 
header, h, defl.h, and def 2 .h to the list Of dependencies for file 2 .o. 


SEE ALSO 

cc(l), make(l) 
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BUGS 

makedepend parses, but does not currently evaluate, theSVR4#predicate(token-iist) preprocessor expression; such 
expressions are simply assumed to be true. This may cause the wrong #inciude directives to be evaluated. 

Imagine you are parsing two files, say fiiei.c and fiie 2 .c, and each includes the fi le def . h. The list of files that def. h 
includes might truly be different when def .h is included by fiiei .c than when it is included by fiie 2 .c. But when 
makedepend arrives at a list of dependencies for a file it iscast in concrete. 

AUTHOR 

T odd Brunhoff, Tektronix, Inc. and M IT Project Athena 

X Verson 11 Release 6 


makestrs 

makestrs— M ake string table C source and header(s) 

SYNOPSIS 

makestrs [-f source] [-abioptions ...] 

DESCRIPTION 

Themakestrs command creates string table C source files and headers. If -f source is not specified, makestrs will read from 
stdin. TheC source file is always written to stdout. makestrs creates one or moreC header files as specified in the source file. 
T he following options may be Specified: -sparcabi, -intelabi, -functionabi, -arrayperabi, and -defaultabi. 

-sparcabi is used on SPARC platforms conforming to the SPARC Compliance Definition, i.e, SVR4/Solaris. 

-intelabi used on Intel platforms conforming to the System V Application Binary Interface (SVR4). 

-eariyR6abi may beused in addition to -intelabi for situations where the vendor wishes to maintain binary compatibility 
between X11R6 public-patch 11 (and earlier) and X11R6 public-patch 12 (and later). 

-functionabi generates a functional application bi nary i nterface to the string table This mechanism imposes a severe 
performance penalty and it's recommended that you not use it. 

-arrayperabi results in a separate array for each string. This is the default behavior if makestrs was compiled with - 
darrayperstr (it almost never is). 

-defaultabi forces the generation of the "normal" string table even ifmakestrs was compiled with -darrayperstr. makestrs is 
almost never compiled with -darrayperstr, so this is the default behavior if no application binary interface (ABI) options are 
specified. 

SYNTAX 

The syntax for string-list file is as follows (items in square brackets are optional): 

#prefix <text> 

#feature <text> 

#externref <text> 

#externdef [<text>] 

[#ctempl <text>] 

#file <filename> 

#table <tablename> 

[#htempl] <text> 

<text> 

[#table <tablename> 

<text> 
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<text> 

#table <tablename> 
■ ■■] 

[#file <filename> 
...] 


You may have one or more#fiie directives. Each #fiie may have one or more #tabie directives. 

T he #pref ix directive determines the string that makestr wil I prefix to each definition. 

T he #teature directive determines the string that makestr will use for the feature-test macro, for example, x-stringdefines. 

T he #externref directive determinesthestring that makestr will use for the extern clause; typically thiswill be extern, but 
M Otif wants it to beexternalref. 

T he #externdet directive determinesthestring that makestr will use for the declaration; typically, thiswill be the null string, 
and M Otif Will use externaldef (_xmstrings). 

The#ctmpi directive determines the name of the file used as a tempi ate for the C source file that is generated. 

Each #tiie <fi i ename> directive will result in a corresponding header fileby that namecontainingtheappropri ate definitions 
as specified by command-line options A single C source file containing the declarations for the definitions in all the headers 
will be printed to stdout. 

The #htmpi di recti ve determi nes the name of the fi le used as a tempi ate for the C header fi le that is generated. 

Each #tabie <t a b i ename> directive will be processed in accordance with theABI. On most platforms all tables wi II be 
catenated into a single table with the name of the first table for that file. T o conform to the Intel ABI, separate tables will be 
generated with the names indicated. 

The tempi ate files specified by the#ctmpi and #htmpi directives are processed by copying line for line from the template file 
to the appropriate output file. The line containi ng the string «<string_table^goes_here»> is not copied to the output file. 
The appropriate data is then copied to the output file and then the remainder of the template file is copied to the output file 

BUGS 

makestrs is not very forgivi ng of syntax errors. Sometimes you need a trailing space after# directives, other times they will 
mess you up. N o warning messages are emitted. 

SEE ALSO 

SPARC Compliance Definition 2.2, SPARC International Inc., 535 M iddlefield Road, Suite 210, M enlo Park, CA 94025 

System 1/ Application Binary Interface, Third Edition, ISBN 0-13-100439-5, UNIX Press, PTR Prentice H all, 113 Sylvan 
Avenue, Englewood Cliffs, NJ 07632 

System 1/ Application Binary Interface, Third Edition, Intel386 Architecture Processor Supplement, ISBN 0-13-104670-5, 
UNIX Press, PTR Prentice H all, 113 Sylvan Avenue, Englewood Cliffs, NJ 07632 

System 1/ Application Binary Interface, Third Edition, SPARC Architecture Processor Supplement, ISBN 0-13-104696-9, 
UNIX Press, PTR Prentice H all, 113 Sylvan Avenue, Englewood Cliffs, NJ 07632 

X Verson 11 Release 6 


mattrib 

mattrib— C hange M S-D O S file attribute flags 

SYNOPSIS 

mattrib [ -a|+a ][-h|+h ][-r|+r ][-s|+s ] msdosfile [ msdosfiles... ] 
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DESCRIPTION 

matt mb adds attribute flags to an M S-D OS file (with the+ operator) or removes attribute flags (with the - operator), 
mattrib allows thefollowing command-line options: 
a Archivebit. Used by somebackup programsto indicate a new file. 

r Read-only bit. Used to indicate a read-only file. Files with this bit set cannot be erased by del or modified, 

s System bit. U sed by M S-D OS to indicatean operating system file, 

h H idden bit. Used to makefiles hidden from dir. 

SEE ALSO 

mtools(l) 

Local 



mbadblocks 

mbadbiocks— Scan an M S-D 0 S floppy and mark its unused bad blocks as bad. 

SYNOPSIS 

mbadblocks drive: 

DESCRIPTION 

mbadblocks scansan M S-D OS floppy for bad blocks. All unused bad blocks are marked as such in the FAT. This is intended 
to be used right after mtormat. It is not intended to salvage bad disks. 

SEE ALSO 

mtools(l) 

BUGS 

This should (but doesn't:-() also try to salvage bad blocksthatarein use by reading them repeatedly, and then mark them 
bad. 

mcd 

mcd — ChangeMS-DOS directory 

SYNOPSIS 

mcd [ msdosdirectory ] 

DESCRIPTION 

Without arguments mcd will report the current device and working directory. Otherwise, mcd changes the current device and 
currentworking directory relative to an M S-D OS filesystem. 

The environmental variable mcwd may be used to locate the file where the device and current working directory information is 
stored. The default is $H 0 ME/.mcwd. Information in thisfileisignored if thefileismorethan six hours old. 

M S-D OS subdirectory names are supported with either the / or \ separator. The use of the \ separator or wildcards will 
require the directory name to be enclosed in quotes to protect it from the shell. 

mcd returns 0 on success or 1 on fai lure. 


SEE ALSO 

mdir(l) 
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BUGS 

Unlike M S-DOS versions of CD, mcd can be used to change to another device. 

It may be wise to remove old .mcwd files at logout. 

Local 


mcookie 

mcookie— Generate magic cookies for xauth 

SYNOPSIS 

mcookie 


DESCRIPTION 


mcookie generates a 128-bit random hexadecimal number for use with theX authority system. Typical usage: 
xauth add :0 . 'mcookie' 


SEE ALSO 

X(l), xauth(l) 


12 February 1995 


mcopy 

mcopy— Copy M S-DOS files to/from UNIX 

SYNOPSIS 

mcopy [ -tnvmoOsSrRA ] sourcefile targetfile 

mcopy [ -tnvmoOsSrRA ] sourcefile [ sourcefiI es ... ] targetdi rectory 
mcopy [ -tnvm ] MSDOSsourcefiI e 

DESCRIPTION 

mcopy copies the specified file to the named file, or copies multiple files to the named directory. The source and target can be 
either MS-DOS or UN IX files. 

The use of a drive letter designation on theM S-DOS files—a: for example- determines the direction of the transfer. A 
missing drive designation implies a U NIX file whose path starts in the current directory. If a source drive letter is specified 
with no attached filename (for example, mcopy a: .), all files are copied from that drive. 

If only a single, M S-D OS source parameter is provided (for example, mcopy a:too.exe), an implied destination of the current 
directory (.) isassumed. 

A filenameof - meansstandard input or standard output, depending on its position on thecommand line, 
mcopy will allow thefollowing command-lineoptions 

t Text fi le transfer, mcopy will translate incoming carriage return/line feeds to linefeeds, 

n N o warning, mcopy will not warn the user when overwriting an existing file, 

v V erbose mode, 

m Preserve the file modification time. 

If the target file already exists, and the -n option is not in effect, mcopy asks whether to overwrite the file or to rename the new 
file. (Seethemtoois(l) man page for details.) 
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SEE ALSO 

mtools(l), mread(l), mwnite(l) 

BUGS 

UnlikeM S-DOS, the + operator (append) from M S-D OS is not supported. 

Local 


md5sum 

md5sum— Generate/check M D5 message digests 

SYNOPSIS 

md5sum [-bv][-c [ file ]] 
md5sum file ... 

DESCRIPTION 

md5sum generates and checks M D5 message digests, as described in RFC-1321. The message digest produced can bethought 
of as a 128-bit "signature" of the input file. T ypically, mdssum is used to verify the integrity of files made available for 
distribution via anonymous FTP (for example, announcements for new versions of irc(l) usually contain M D5 signatures). 

M essage digests for a tree of files can be generated with a command similar to the following: 

find . -type f -print | xargs md5sum 

The output of this command is suitable as input for the -c option. 

OPTIONS 

-c [file] 

-v 
-b 

HISTORY 

T he md5sum program was written by Branko Lankester and may be freely distributed. The original source code is in the M IT 
PGP 2.6.2 distribution. Those concerned about the integrity of this version should obtain the original sources and compile 
their own version. 

The underlying implementation of Ron Rivest'sM D 5 algorithm was written by Colin Plumb and is in the public domain. 
(Equivalent code is also avai lablefrom RSA D ata Security, Inc.) 

SEE ALSO 

sum(l), cksum(l), pgp(l) 

Linux 1.0,11 February 1995 


Check message digests. Input is taken from stain or from the specified tile. The input should be in the 
same format as the output generated by massum. 

Verbose. Print filenames when checking. 

Readfilesin binary mode; otherwise, end-of-fi le conventions will beignored. 


mdel 

maei— Delete an M S-D OS file 

SYNOPSIS 


mdel [ -v ] msdosfile [ msdosfi I es ... ] 



mdir 

DESCRIPTION 

mdei deletes a file on an M S-D OS filesystem, 
mdei will allow the following command-line option: 
v Verbosemode. Echothefilenamesastheyareprocessed. 

mdei will ask for verification prior to removing a read-only file. 

SEE ALSO 

mtools(l) 

Local 



mdeltree 

mdeitree— Remove an M S-D 0 S di rectory tree 

SYNOPSIS 

mdeltree [ -v ] msdosdi rectory [ msdosdi rector i es... ] 

DESCRIPTION 

mdeltree removes a directory and all thefilesand subdirectories it contains from an M S-D OS filesystem, mdeltree will allow 
the following command-line option: 

v Verbosemode. D isplays each file or directory as it is removed. 

An error occurs if the directory does not exist. 

SEE ALSO 

mtools(l), mrd(l) 

Local 


mdir 

mdir— D isplay an M S-D OS directory 

SYNOPSIS 

mdir [ -w ] msdosdi rect or y 

mdir [ -w ][-a ] msdosfile [ msdosfi I es ... ] 

DESCRIPTION 

mdir displays the contents of an M S-D OS directory, 
mdir will allow the followi ng command-line options: 

w Wide output. This option will print the filenames across the page without displaying the file size or creation date, 

a Also list hidden files. 

An error occurs if a component of the path is not a di rectory. 

SEE ALSO 

mtools(l) 


Local 
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merge 

merge— T h ree-way fi le merge 

SYNOPSIS 

merge [ options ] fiI el fiI e 2 fiI e 3 

DESCRIPTION 

merge incorporates all changes that lead from f i i e 2 to f i 1 e 3 into f i 1 ei. The result ordinarily goes into f i 1 ei. merge is useful 
for combining separate changes to an original. Supposef i 1 e2 is the original, and both f i 1 e 1 and f i 1 e 3 are modifications of 
f i 1 e2. Then merge combines both changes. 

A conflict occurs if both f i 1 e 1 and f i 1 e 3 have changes in a common segment of lines. If a conflict is found, merge normally 
outputs a warning and brackets the conflict with «««< and »»»> lines. A typical conflict will look like this: 

«««< f i | e A 
lines in file A 


lines in file B 
»»»> file B 

If there are conflicts, the user should edit the result and delete one of the alternatives. 

OPTIONS 

-a 0 utput conflicts using the -a style of d±ff3(l), if supported by diff3. This merges all changes leading from fiie 2 
to tiie3 into tiiei, and generates the most verbose output. 

-e, -e These options specify conflict styles that generate less information than -a. See dit t3(l) for details. The default is 
-e. W ith -e, merge does not warn about conflicts. 

-l label This option may be given up to three times, and specifies labels to be used in place of the corresponding filenames 
in conflict reports. That is, merge-Lx-L y -lz a b c generates output that lookslikeit camefrom files x, y, and z 
instead of from files a, b, and c. 

-p Send results to standard output instead of overwriting tiiei. 

-q Quiet; do not warn about conflicts. 

-v Print RCS'sversion number. 

DIAGNOSTICS 

Exit status iso for no conflicts, 1 for some conflicts, 2 for trouble. 

IDENTIFICATION 

Author: Walter F. Tichy. 

M anual Page Revision: 5.7; Release D ate: 1995/06/01. 

Copyright © 1982,1988,1989 Walter F. Tichy. 

Copyright© 1990,1991,1992,1993,1994,1995 Paul Eggert. 

SEE ALSO 

diff3(1), diff(l), rcsmerge(l), co( 1) 

BUGS 

It normally does not make sense to merge binary files as if they were text, but merge tries to do it anyway. 


GNU, 1 Junel995 
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mesg 

mesg— D isplay (do not display) messages from other users 

SYNOPSIS 

mesg [n][y] 

DESCRIPTION 

The mesg utility is invoked by a users to control write access others have to the terminal device associated with the standard 
error output. If write access is allowed, then programs such astaik(l) and write(l) may display messages on the terminal. 

T raditionally, write access is allowed by default. H owever, as users become more conscious of various security risks, there is a 
trend to remove write access by default, at least for the primary login shell. To make sure your ttys are set the way you want 
them to beset, mesg should be executed in your login scripts 

0 ptions available: 
n Disallows messages 

y Perm its messages to be displayed 

If no arguments are given, mesg displays the present message status to the standard error output. 

The mesg utility exits with one of the following values: 

\0 M essages are allowed. 

\i M essages are not allowed. 

i An error has occurred. 

FILES 

/dev/[pt]ty[pq]? 

SEE ALSO 

biff(l), talk(l), write(l), wall(l), login(l), xterm(l) 

HISTORY 

A mesg command appeared in version 6 AT&T UN IX. 

Linux 1.2,10 March 1995 


mformat 

mformat— Add an M S-D OS filesystem to a low-level formatted disk 

SYNOPSIS 

mformat [ -t tracks ] [ -h heads ] [ -s sectors ] [ -1 volume label ] 

[ -S sizecode ] [ -2 sectors on track 0 ] [ -M software sector size ] 

[ -a ] [-X ] [-C ][-H hidden sectors ] drive: 

DESCRIPTION 

mformat adds a minimal M S-D OS filesystem (boot sector, FAT, and root directory) to a disk that has already been formatted 
by a U NIX low-level format. 

Thefollow options are supported: (Thes, 2, 1, and m optionsmay not exist if thiscopy of mtoois has been compiled without 
theusE_2M option). 
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t The number of tracks (not cylinders). 

h The number of heads (sides). 

s The number of sectors per track. If the 2m option is given, number of 512-byte sector equivalents on generic tracks 

(that is, not head 0 track). I f the 2m option isnot given, number of physical sectors per track (which may be bigger 
than 512 bytes). 

1 An optional volume label. 

s Thesizecode.Thesizeofthesectoris 2 " (sizecode + 7). 

2 2m format. The parameter to this option describes the number of sectors on track 0 , head 0 . This option is 
recommended for sectors bigger than normal. 

1 D on't use a 2m format, a/en if the current geometry of the disk is a 2m geometry. 

m Software sector size. This parameter describes the sector size in bytes used by the MS-DOS filesystem. By default 

it isthe physical sector size. 

a If this option is given, an Atari-style serial number is generated. Ataris store their serial number in theOEM label. 

x Formats thedisk as an Xdf disk. Xdf disks are used by OS/2. Thisformat can hold 1756Kb, and is faster than the 

equivalent 2m formats. Thedisk has first to be low-level formatted using the xdf copy utility included in thetdutiis 
package. 

c Creates the disk image fileto install theM S-D OS filesystem on it. Obviously, this is useless on physical devices 

such as floppies and hard disk partitions. 

h N umber of hidden sectors. This parameter is useful for formatting hard disk partitions which are not aligned on 

track boundaries (in other words first head of first track doesn't belong to the partition, but contains a partition 
table). In that case the number of hidden sectors is in general the number of sectors per cylinder. This is untested. 

n Serial number. 

T 0 format a disk at a density other than the default, you must supply (at least) those command-line parameters that are 

different from the default. 

Mformat returnso on success or 1 on failure. 

SEE ALSO 

mlabel(l) 

BUGS 

Requires a low-level format utility from U N IX. 

Doesn't detect (or record) bad block information. 

Local 


mgrtopbm 

mgrtopbm— C onvert an M G R bitmap into a portable bitmap 

SYNOPSIS 

mgrtopbm [mgr f i I e] 

DESCRIPTION 

mgrtopbm reads an MGR bitmap as input and produces a portable bitmap as output. 

SEE ALSO 

pbmtomgr(l), pbm( 5 ) 
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AUTHOR 

Copyright© 1989 byjef Poskanzer. 


mkdir 

mkdir— M akedirectories 

SYNOPSIS 

mkdir [-p] [-m mode] [--parents] [--mode=mode] [--help] [--version] dir... 

DESCRIPTION 

This manual page documents the GN U version of mkdir. mkdir creates a directory with each given name. By default, the 
modeof created directories is 0777 minus the bits set in theumask. 


OPTIONS 


-m, --mode mode Set the mode of created directories to mode, which is symbolic as in chmod and uses the default mode as the 
point of departure 

-p, - parents Ensure that each given directory exists. Create any missing parent directories for each argument. Parent 
directories default to theumask modified by u+wx. Do not consider an argument directory that already 
exists to bean error. 


--help Print a usage message on standard output and exit successfully, 

--version Print version information on standard output then exit successfully. 


GNU File Utilities 


mkdirhier 

mkdirhier — M ake a directory hierarchy 

SYNOPSIS 

mkdirhier directory ... 

DESCRIPTION 

The mkdirhier command creates the specified directories. Unlike mkdir, if any of the parent directories of the specified 
directory do not exist, it creates them aswell. 

SEE ALSO 

mkdir(l) 

X Vera on 11 Release 6 


mkfifo 

mkfito — M akeFIFOsfnamed pipes) 

SYNOPSIS 


mkfifo [-m mode] [--mode=mode] [--help] [--version] filename... 
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DESCRIPTION 

This manual page documents the GN U version of mkfifo. mktito creates a FIFO with each given name. By default, the mode 
of created FIFO sis 0666 minus the bits set in theumask. 

OPTIONS 

-m, --mode mode Set the mode of created FI FO s to mode, which issymbolic as in chmod and uses the default mode as the 
point of departure. 

--help Print a usage message on standard output and exit successfully. 

--version Print version information on standard output then exit successfully. 

GNU File Utilities 


mkmanifest 

mkmanifest— Create a shell script to restore UN IX filenames 

SYNOPSIS 

mkmanifest [files ] 

DESCRIPTION 

mkmanifest creates a shell script that will aid in the restoration of U NIX filenames that got clobbered by theM S-D OS 
filename restrictions. M S-D OS filenames are restricted to eight-character names, three-character extensions, uppercase only, 
no device names, and no illegal characters. 

The mkmanifest program is compatible with the methods used in pcomm, arc, and mtoois to change perfectly good UNIX 
filenames to fit theM S-D OS restrictions. 

EXAMPLE 

Say you want to copy the following U NIX files to an M S-D OS disk (using the mcopy command): 

very_long_name 

2 .many.dots 

illegal: 

good.c 

prn.dev 

Capital 

mcopy will convert the names to 

very_lon 

2 xmany.dot 

illegalx 

good.c 

xprn.dev 

capital 

The command: 

mkmanifest very_long_name 2 .many.dots illegal: good.c prn.dev Capital > manifest 

would produce the following: 

mv very_lon very_long_name 
mv 2xmany.dot 2.many.dots 
mv illegalx illegal: 
mv xprn.dev prn.dev 
mv capital Capital 
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N otice that good.c did not require any conversion, so it did not appear in the output. 

Suppose I've copied these files from the disk to another UNIX system, and I now want the files back to their original names. 

If the file manifest (the output captured above) was sent along with those files, it could be used to convert the filenames. 

BUGS 

The short names generated by mkmanifest follow the old convention (from mtoois- 2 . 0 . 7 ) and not the one from Windows 95 
and mtoois- 3 . 0 . 

SEE ALSO 

arc(l), pcomm(l), mtools(l) 

Local 


mknod 

mknod — M akespecial files 

SYNOPSIS 

mknod [options] filename {bcu} major minor 
mknod [options] filename p 

Options: 

[-m mode] [--mode=mode] [--help] [--version] 

DESCRIPTION 

This manual page documents the GN U version of mknod. mknod creates a FIFO, character special file, or block special file with 
thegiven filename By default, the mode of created files is 0666 minus thebits set in theumask. 

The argument after filename specifies the type of file to make: 
p for a FIFO 

b for a block (buffered) special file 
c or u for a character (unbuffered) special file 

When making a block or character special file, the major and minor device numbers must be given after the file type. 

OPTIONS 

-m, --mode mode Set the mode of created files to mode , which is sym bolic as in chmod and uses the default mode asthe point 
of departure. 

--help Print a usage message on standard output and exit successfully. 

--version Print version information on standard output then exit successfully. 

GNU File Utilities 

mlabel 

miabei— M akean M S-DOS volumelabel 

SYNOPSIS 

mlabel [ -v ] drive: [ newlabel ] 
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DESCRIPTION 

miabei displays the current volume label, if present. If newj abei is not given, and if neither thee nor the s options are set, it 
prompts the user for a new volume label. T o delete an existing volume label, press return at the prompt. 

miabei supportsthefollowing command-lineoption: 

v Verbose mode. Display the new volume label if the label supplied isinvalid. 

c Clears an existing label, without prompting the user, 

s Showstheexisting label, without prompting the user. 

Reasonablecareistaken to createavalid M S-D OS volume label. If an invalid label is specified, miabei will change the label 
(and display thenew label if the verbose mode is set). 

Miabei returns 0 on successor i on failure. 

SEE ALSO 

mformat(l) 

Local 


mmd 

mmd— M ake an M S- D 0 S su bd i recto ry 

SYNOPSIS 

mmd [ -voOsSrRA ] msdosdi rectory [ msdosdi rector i es ... ] 

DESCRIPTION 

mmd makes a new directory on an M S-D OS filesystem. 

mmd will allow thefollowing command-lineoption: 

v Verbose mode. D isplay the new directory name as it iscreated. 

An error occurs if the directory already exists. 

SEE ALSO 

mtools(l), mrd(l), 

Local 


mmount 

mmount— Mount an MS-DOS disk 

SYNOPSIS 

mmount msdosdrive [mountargs] 

DESCRIPTION 

mmount reads the boot sector of an M S-D OS disk, configures the drive geometry, and finally mounts it, passing mountargs to 
mount. If no mount arguments are specified, the name of the device is used. If the disk is write-protected, it is automatically 
mounted read-only. 



more 


327 


SEE ALSO 

mtools(l), mount(8) 


Local 


mmove 

mmove— M ove or rename an existing M S-D OS file or subdirectory 

SYNOPSIS 

mmove [ -voOsSrRA ] sourcefile targetfile 

mmove [ -voOsSrRA ] sourcefile [ sourcefiles... ] targetdirectory 

DESCRIPTION 

mmove moves or renames an existing M S-D OS file or subdirectory, 
mmove will allow thefollowing command-lineoption: 

v Verbosemode. Display the new filename if the name supplied isinvalid. 

Additionally, it allows the clash-handling options described in the man page for mtoois. 

M S-D OS subdirectory names are supported with either the / or \ separator. The use of the \ separator or wildcards will 
require the names to be enclosed in quotes to protect them from the shell. U nlike the M S-D OS version of move, mmove is able 
to move subdirectories. 

SEE ALSO 

mren(l), mtools(l) 


more 

more— File perusal filter for crt viewing 

SYNOPSIS 

more [-dlfpcsu] [ -num] [ + / pattern] [+ linenum] 

DESCRIPTION 

more is a filter for paging through text one screenful at a time. This version is especially primitive. Users should realize that 
iess(l) provides more(l) emulation and extensive enhancements 

OPTIONS 

Command-line options are described in thefollowing list. Options are also taken from the environment vari able more (make 
sure to precedethem with a hyphen (-)) but command-line optionswill override them. 

-num Thisoption specifies an integer that is the screen size (in lines). 

-d more Will prompt the user With the message [Press space to continue, ' q 1 to quit.] and will display [Press 1 h 1 

for instructions.] instead of ringing the bell when an illegal key ispressed. 

-l more usually treats (form feed) as a special character, and will pause after any line that contains a form feed. The -i 
option will prevent this behavior. 

-f Causes more to count logical, rather than screen lines (that is long lines are not folded). 

-p Do not scroll. Instead, clear the whole screen and then display the text. 

-c Do not scroll. Instead, paint each screen from the top, clearing the remainder of each line as it is displayed. 
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-s Squeeze multiple blank lines into one. 

-u Suppressunderlining. 

+/ T he +/ option specifies a string that will be searched for before each file is displayed. 

+num Start at line number. 

COMMANDS 

Interactive commands for more are based on vi( 1). Some commands may be preceded by a decimal number, called k in the 
following descriptions In thefollowing descriptions *x means controi-x. 

hor? Help: display a summary of these commands If you forget all the other commands, remember thisone. 

space D isplay next k lines of text. D efaultsto current screen size. 

z D isplay next k lines of text. D efaults to current screen size. Argument becomes new default. 

return D isplay next k lines of text. D efaults to i. Argument becomes new default, 

d or “d Scroll k lines. D efault is current scroll size, initially 11. Argument becomes new default, 

q or Q INTERRUPT Exit. 

s Skip forward k lines of text. Defaults to i. 

t Skip forward k screenfuls of text. D efaults to i. 

bor "b Skip backwardsk screenfuls of text. Defaults to i. 

1 Go to placewhereprevioussearch started. 

= Display current line number. 

/pattern Search for kth occurrence of regular expression. Defaults to i. 

n Search for kth occurrence of last r.e. D efaults to i. 

!<cmd> or: !<cmd> Execute <cmd> in a subshell, 
v Start up /usr/bin/vi at current line. 

'l Redraw screen. 

:n Go to kth next file. Defaults to i. 

: p Go to kth previous file. Defaults to i. 

ic :t Display current filename and line number. 

Repeat previous command. 

ENVIRONMENT 

more utilizes the following environment variables, if they exist: 
more This variable may be set with favored optionsto more. 

shell Current shell in use (normally set by the shell at login time). 

term Specifies terminal type, used by more to get the terminal characteristics necessary to manipulate the screen. 

SEE ALSO 

vi(l), less(l) 

AUTHORS 

Eric Shienbrood, UC Berkeley. M odified by Geoff Peck, UCB to add underlining, single spacing. M odified by John 
Foderaro, UCB to add -c and more environment variable. 

HISTORY 

Themore command appeared in BSD 3.0. Thisman page documents more version 5.19 (Berkeley 29 J une 1988), which is 
currently in use in the Linux community. D ocumentation was produced using several other versions of the man page, and 
extensive inspection of the source code. 


Linux0.98, 25 December 1992 
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mrd 

mrd— Remove an MS-DOS subdirectory 

SYNOPSIS 

mrd [ -v ] msdosdirectory [ msdosdirectories... ] 

DESCRIPTION 

mrd removes a directory from an M S-D OS filesystem, mmd will allow thefollowing command-line option: 
v Verbose mode. D isplay the directory name as it is removed. 

An error occurs if the directory does not exist or is not empty. 

SEE ALSO 

mtools(l), mmd(l), mdeltree(l) 

Local 


mread 

mread — Read (copy) an M S-D OS file to U NIX 

SYNOPSIS 

mread [ -tnvmoOsSrRA ] msdosfile unixfile 

mread [ -tnvmoOsSrRA ] msdosfile [ msdosfi I es ... ] uni xdi rectory 

DESCRIPTION 

This command is obsolete, and only supplied for backwards compatibility reasons with old scripts Usemcopy instead. 

SEE ALSO 

mcopy(l), mtype(l), mtools(l) 


mren 

mren— Rename or move an existing M S-DOSfile or subdirectory 

SYNOPSIS 

mren [ -voOsSrRA ] sourcefile targetfile 

mmove [ -voOsSrRA ] sourcefile [ sourcefiles... ] targetdirectory 

DESCRIPTION 

mren renames an existing file on an M S-D OS filesystem. 

Mren will allow the following command-line option: 

voOsSrRA Verbosemode. Display the new filename if the name supplied isinvalid. 

If the first syntax isused (only one sourcefile), and if the target name doesn't contain any slashes or colons the file (or 
subdirectory) will be renamed in the same directory, instead of being moved to the current mod directory as would be the case 
with mmove. U nlike the M S-D 0 S version of ren, mren can be used to rename directories. 
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BUGS 

Unlike theM S-DOS version of ren, mren can beused to rename directories. 

SEE ALSO 

mcd(l) 

Local 


mtest 

mtest— Test themtoois configuration files 

SYNOPSIS 

mtest 

DESCRIPTION 

mtest reads themtoois configuration files and prints the cumulative configuration to stdout. The output can beused as a 
configuration file itself (although you might want to remove redundant clauses). You may use this program to convert old- 
style configuration files into new style configuration files. 

SEE ALSO 

mtools(5) 

Local 


mtools 

mtoois— A collection of tools for manipulating M S-DOS files 

SYNOPSIS 

T he mtoois are 

matt mb— Change M S-DOS file attribute flags 

mbadbiocks— Test a floppy disk, and mark the bad blocks in the FAT 

mod— ChangeMS-DOS directory 

mcopy— Copy M S-DOS files to/from UNIX 

mdei— Delete an M S-DOS file 

mdir— D isplay an M S-DOS directory 

mformat— Add an M S-D OS filesystem to a low-level formatted floppy disk 

miabei— M akean M S-DOS volumelabel 

mmd— M ake an MS-DOS subdirectory 

mmount— Mount an MS-DOS disk 

mrd— Remove an MS-DOS subdirectory 

mmove— M ove or rename an M S-D OS file or subdirectory 

mren— Rename an existing M S-D OS file 

mtype— D isplay contents of an M S-D OS file 

mtest— Test and display the configuration 



mtest 



DESCRIPTION 

mtoois is a public domain collection of programs to allow U NIX systems to read, write, and manipulate files on an MS-DOS 
filesystem (typically a floppy disk). W here reasonable, each program attempts to emulate the M S-D OS equivalent command. 
H owever, unnecessary restrictions and oddities of DOS are not emulated. For instance, it is possible to move subdirectories 
from one subdirectory to another. 

M S-D OS filenames are optionally composed of a drive letter followed by a colon, a subdirectory, and a filename. Filenames 
without a drive letter refer to UN IX files. Subdirectory names can use either the / or \ separator. The use of the \ separator 
or wildcards will require the names to be enclosed in quotesto protect them from the shell. (N ote Wildcards in U NIX 
filenames should not be enclosed in quotes, because here users want the shell to expand them.) 

DIFFERENCES WITH MS-DOS 

The regular expression "pattern matching" routines follow theU NI X-style rules. For example * matches all M S-D OS files 
in lieu of *.*. The archive, hidden, read-only, and system attribute bits are ignored during pattern matching. 

All optionsusethe - (minus) flag, not / asyou'd expect in M S-DOS. 

M ost mtoois commands allow multiple filename parameters, which doesn't follow M S-DOS conventions, but which is more 
user friendly. 

WORKING DIRECTORY 

Themed command is used to establish the device and the current working directory (relative to the M S-D OS filesystem); 
otherwise, the default is assumed to be a: /. However, unlike M S-DOS, there is only one working directory, and not one per 
drive. 

VFAT-STYLE LONG FILENAMES 

This version of mtoois supports V FAT-style long filenames. If a U NIX filename is too long to fit in a short D OS name, it is 
stored as a VFAT long name, and a companion short name is generated. This short name is what you see when you examine 
the disk with apre-7.0 version of DOS. The following table shows some examples of short names: 


UNIX Name MS-DOS Name Reason for the Change 


thisisatest 

alain.knaff 

prn.txt 

.abc 

hot+cold 


THISISAT 
ALAIN.KNA 
XRN.TXT 
X.ABC 
HOTXCOLD 


Filenametoo long 
Extension too long 
PRN isadevicename 
N ull filename 
Illegal character 


The initial U NI X-style filename (whether long or short) is also called primary name, and the derived short name is also called 
secondary name 

Example: 

mcopy /etc/motd a:Reallylongname 

mtoois createsa VFAT entry for Reaiiyiongname, and uses reallylo asashort name. Reaiiyiongname istheprimary name, and 
reallylo is the secondary name 

In this example: 

copy /etc/motd a:motd 

motd fits into the DOS filename limits mtoois doesn't need to derivate another name, motd istheprimary name, and there is 
no secondary name. 

In a nutshell: The primary name is the long name, if one exists, or the short name if there is no long name 
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NAMECLASHES 

When writing a file to disk, its long name (primary name) or short name may collide with an already existing file or 
directory. This may happen for all commands that create new directory entries: mcopy, mmd, mren, mmove, mwrite, and mread. 

When a name clash happens, mtoois asks you what it should do. It offers several choices: 
overwrite 0 verwritesthe existing file. It is not possible to overwrite a directory with afile. 

rename Renames the newly created file mtoois will prompt for the new filename, 

autorename Renames the newly created file mtoois will chose a name by itself, without prompting, 

skip Gives up on thisfile and moves on to the next (if any). 

T o choose an option, type its first letter at the prompt. If you use a lowercase letter, the option applies for thisfile only; if 
you use an uppercase letter, the option applies to all files. 

You may also choose options (for all files) on thecommand linewhen invoking mtoois: 

-o Overwrites primary names by default 
-o Overwrites secondary names by default 
-r Renames primary name by default 
■ r Renamessecondary name by default 
-a Autorenames primary name by default 
-a Autorenames secondary name by default 
-s Skips primary name by default 

-s Skips secondary nameby default 

-m Asks user what to do with primary name 

-m Asks user what to do with secondary name 

By default, the user is prompted if the primary name clashes, and the secondary nameisautorenamed. 

If a name clash occurs in aUN IX directory, mtoois only asks whether to overwrite the file or to skip it. 

CASE SEN SITIVITY 0 F TH E VFAT FILESYSTEM 

TheVFAT filesystem is able to remember the case of the filenames. H owever, filenames that differ only in case are not 
allowed to coexist in the same directory. For example if you store a file called LongFiieName on a VFAT filesystem, mdir will 
show thisfile as LongFiieName, and notasLongfiiename. H owever, if you then try to add LongFUename to the same directory, 
it will be refused, because case isignored for clash checks. 

TheVFAT filesystem allows the storing of the case of a filename in the attribute byte, if all letters of thefilename are the 
samecase, and if all letters of the extension are the same case too. mtoois uses this information when displaying the files, and 
also to generate the U NIX when mcopying to a UN IX directory. This may have unexpected results when applied to files 
written using a pre-7.0 version of DOS; indeed, these filenames map to all uppercase. This is different from the behavior of 
the old version of mtoois, which used to generate lowercase U NIX filenames. 


XDFDISKS (LIN UX ONLY) 

Xdf is a high-capacity format supported by 0 S/2. It can hold 1,840KB per disc. T hat's not very high compared to the best 
2m formats, but its main advantage is that it is fast: 600 milliseconds per track. That's faster than the good old 21 sector 
format, and almost as fast as the standard 18 sector format. In order to access these disks, settheuse_xdf variable for the 
drive. Seemtoois(5) for details on how to do this. Fast Xdf access is only avail able for kernels more recent than 1.1.34. 


CAUTION 


Attention distributors: If mtoois is compiled on Linux, on a kernel more recent than 1.3.34, it won't run on an older 
kernel. FI owever, if it has been compiled on an older kernel, it will still run on a newer kernel, except that Xdf access is 







mtype 



slower. It is recommended that distribution authors only include mtoois binaries compiled on kernels older than 1.3.34 
until 2.0 comes out. W hen 2.0 isout, mtoois binaries compiled on newer kernels may (and should) be distributed, mtoois 
binaries compiled on kernels older than 1.3.34 won't run on any kernel 2.1 or later. 


EXIT CODES 

All the mtoois commands return 0 on success, 1 on utter failure, or 2 on partial failure. All the mtoois commands perform a 
few sanity checks before going ahead, to make sure that the disk is indeed an M S-DOS disk (as opposed to, say, an ext2 or 
minix disk). These checks may reject partially corrupted disks, which might otherwise still be readable. T 0 avoid these 
checks, set the mtools_skip_check environmental variable 

SEE ALSO 

mattrib(l), mbadblocks(l), mcd(l), mdel(l), mformat(l), mmove(l), mrd(l), mren(l), mtype(l), mcopy(l), mdir(l), mlabel(l), 
mmd(l), mmount(l) 

BUGS 

An unfortunate side effect of not guessing the proper device (when multiple disk capacities are supported) is an occasional 
error message from the device driver. These can be safely ignored. 

The fat checking code chokes on 1.72M B disks mformatted with pre-2.0.7 mtoois. Set the environmental variable 
mtools_fat_compat i b i lity to bypass the fat checking. 

The support for non-Linux OS variants has not been tested for a longtime. It may contain bugs, or a/en not work at all. 

Local 


mtvtoppm 

mtvtoppm— Convert output from the M TV or PRT ray tracers into a portable pixmap 

SYNOPSIS 

mtvtoppm [ mt v f i I e ] 

DESCRIPTION 

mtvtoppm reads an input file from M ark Van DeWettering's MTV ray tracer and produces a portable pixmap as output. 
ThePRT ray tracer also producesthisformat. 

SEE ALSO 

ppm( 5 ) 

AUTHOR 

Copyright© 1989 byjef Poskanzer 

2 February 1989 


mtype 

mtype— D isplay contents of an M S-DOS file 

SYNOPSIS 

mtype [ -ts ] msdosfile [ msdosfiles ... ] 
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DESCRIPTION 

mtype displays the specified M S-DOSfileon thescreen. 
mtype will allow thefollowing command-lineoptions: 

t Text file viewing, mtype will translate incoming carriage return/li ne feeds to linefeeds, 

s Strip high bit. mtype will strip the high bit from the data. 

M S-D OS subdirectory names are supported with either the / or \ separator. The use of the \ separator or wildcards will 
require thenames to be enclosed in quotes to protect them from the shell. 

Themed command may be used to establish the device and the current working directory (relative to M S-D OS); otherwise, 
the default isA:/. 

mtype returns© on success, i on utter failure, or 2 on partial failure. 

SEE ALSO 

mcd(l), mread(l) 

BUGS 

Allows multiple arguments, which does not follow the MS-DOS convention. 

Local 


mv 

mv— Renamefiles 

SYNOPSIS 

mv [options] source dest 
mv [options] source... directory 

Options: 

[-bfiuv] [-S backup-suffix] [-V {numbered,existing,simple}] [--backup] [--force] 
[--interactive] [--update] [--verbose] [--suffix=backup-suffix] 

[- - version-control={numbered,existing,simple}] [--help] [--version] 


DESCRIPTION 

This manual page documents the GN U version of mv. If the last argument names an existing directory, mv moves each other 
given file into a file with the same name in that directory. Otherwise, if only two files are given, it moves thefirst onto the 
second. It is an error if the last argument is not a directory and more than two files are given. It can move only regular files 
across filesystems. If a destination file is unwritable the standard input is a tty, and the -f or - -force option is not given, mv 
prompts the user for whether to overwrite the file If the response does not begin with y ory, the file is skipped. 


OPTIONS 

-b, - -backup 

-f, - -force 

-i, --interactive 

-u, --update 

-v, --verbose 
- -help 
--version 


M ake backupsof filesthatare about to be removed. 

Remove existing destination files and never prompt the user. 

Prompt whether to overwrite each destination file that already exists. If the response does 
not beginwith yory, thefile is skipped. 

Do not move a nondirectory that has an existing destination with the same or newer 
modification time 

Print the name of each file before moving it. 

Print a usage message on standard output and exit successfully. 

Print version information on standard output, then exit successfully. 
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-S, --suffix backup-suffix 


-V, --version-control 
{numbered,existing,simple} 


The suffix used for making simple backup files can beset with thesiMPLE_BACKUP_suFFix 
environment variable, which can be overridden by thisoption. If neither of those is given, 
the default is ", asitisin Emacs. 

The type of backups made can beset with the version_control environment variable, which 
can beoverridden by thisoption. If version_control isnot set and thisoption isnot given, 
the default backup type is existing. T he value of the version_control environment variable 
and the argument to thisoption are like the G N U Emacs version-control variable; they 
also recognize synonyms that are more descriptive. 

T he valid values are the following (unique abbreviations are accepted): 
t or numbered --Always make numbered backups 

nil or existing -M ake numbered backups of files that already have them, simple backups of 
the others. 

never or simple— Always make simple backups. 

GNU File Utilities 
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mwrite— Low-level write (copy) a U NIX file to MS-DOS 

SYNOPSIS 

mwrite [ -tnvmoOsSrRA ] unixfile msdosfile 

mwrite [ -tnvmoOsSrRA ] unixfile [ unixfiles... ] msdosdi rectory 

DESCRIPTION 

Thiscommand is obsolete and only supplied for backward compatibility reasonswith old scripts Usemcopy instead. 

SEE ALSO 

mcopy(l), mtools(l) 

Local 


namei 

namei— Follow a pathnameuntil a terminal point isfound 

SYNOPSIS 

namei [ - mx ] pathname [ pathname ... ] 

DESCRIPTION 

namei uses its arguments as pathnames to any type of U NIX file (symlinks files, directories, and so forth), namei then follows 
each pathnameuntil a terminal point isfound (a file, directory, char device, and so on). If it finds a symbolic link, the user 
showsthelink, and startsfollowing it, indenting the output to show the context. 

T his program is useful for finding too many levels of symbolic links problems. 

For each lineoutput, namei outputs the following characters to identify the file types found: 
f: Thepathnametheuser is currently trying to resolve 

d D irectory 

1 Symbolic link (both thelink and its contents are output) 

s Socket 
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b Block device 

c Character device 

Regular file 

? An error of somekind 

Namei prints an informative message when the maxi mum number of symbolic links this system can have has been exceeded. 

OPTIONS 

-x Show mount point directories with aD rather than ad. 

-m Show the mode bits of each file type in the style of is(l), for example, rwxr-xr-x. 


AUTHOR 

Roger Southwick (rogers@amadeus.wr.tek.com) 

BUGS 

T o be discovered 

CAVEATS 

namei will follow an infinite loop of symbolic links forever. T o escape, usesiGiNT (usually "c). 

SEE ALSO 

ls(l), stat(l) 

Local 


newaliases 

newaiiases— Rebuild the database for the mail aliases file 

SYNOPSIS 

newaliases 

DESCRIPTION 

newaliases rebuilds the random access database for the mail aliases file It must be run each timeit ischanged in order for the 
change to take effect. 

SEE ALSO 

aliases( 5 ), sendmail(8) 

HISTORY 

The newaliases command appeared in BSD 4.0. 

BSD 4, 30July 1991 


newgrp 

newgrp— Log in to a new group 

SYNOPSIS 


newgrp [ group ] 



nl 
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DESCRIPTION 

newgrp changes the group identification of its caller, analogously to iogin(l). The same person remains logged in, and 
the current directory is unchanged, but calculations of access permissions to files are performed with respect to the new 
group ID. 

If no group is specified, the GID ischanged to thelogin GID. 

FILES 

/etc/group 

/etc/passwd 


SEE ALSO 

login(l), group( 5 ) 


Linux 0.99, 9 October 1993 


nl 

m— N umber lines of files 

SYNOPSIS 

nl [-h header-style] [-b body-style] [-f footer-style] [-p] [-d cc] 

[-v start-number] [-i increment] [-1 lines] [-s line-separator] 

[-w line-no-width] [-n {ln,rn,rz}] [--header-numbering=style] 

[--body-numbering=style] [--footer-numbering=style] 

[--first-page=number] [--page-increment=number] [--no-renumber] 

[- -join-blank-lines=number] [--number-separator=string] 

[--number-width=number] [--number-format={ln,rn,rz}] 

[--section-delimiter=cc] [--help] [--version] [file...] 

DESCRIPTION 

This manual page documents the GN U version of ni. m copies each given file, or the standard input if none are given or 
when a file named - isgiven, to thestandard output, with line numbers added to someorall of thelines. 

m considers its input to be composed of logical pages; by default, the line number is reset to i at the top of each logical page, 
ni treats all of the input files as a single document; it does not reset line numbers or logical pages between files. 

A logical page consists of three sections: header, body, and footer. Any of the sections can be empty. Each can be numbered 
in a different style from the others. 

The beginnings of the sections of logical pages are indicated in the input file by a line containing nothing except one of the 
following delimiter strings: 

\:\:\: start of header 
\:\: start of body 
\: start of footer 

The two characters from which these strings are made can be changed with an option (see the next subsection), but the 
pattern and length of each string cannot be changed. 

The section delimiter strings are replaced by an empty line on output. Any text that comes before the first section delimiter 
string in the input file is considered to be part of a body section, so a file that does not contain any section delimiter strings is 
considered to consist of a single body section. 

OPTIONS 

-h, --header-numbering=style See --footer-numbering. 

-b, --body-numbering=style See --footer-numbering. 
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-f, --footer-numbering=style 


-p, - -no-renumber 
-v, --first-page=number 
-i, --page-increment=number 
-1, - -join-blank-lines=number 


-s, --number-separator=string 

-w, - - number-width=number 
-n, --number-format={ln,rn,rz} 


-d, - - section-delimiter=cc 


--help 
--version 


Select the numbering stylefor lines in thefooter section of each logical page. When a line is 
not numbered, the current line number is not incremented, but the line number separator 
character isstill prepended to the line. T he styles are 
a Number all lines 

t N umber only nonempty lines (default for body) 

n N umber no lines (default for header and footer) 

pregexp N umber only lines that contain a match for regexp 

Do not reset the line number at the start of a logical page. 

Set the initial line number on each logical page to number (default i). 

Increment line numbers by number (default i). 

Consider number (default i) consecutive empty lines to beonelogical linefor numbering, 
and only number the last one. W here fewer than number consecutive empty lines occur, do 
not number them. An empty line is one that contains no characters, not even spaces or tabs. 
Separate the line number from the text line in the output with string (default is a tab 
character). 

U se number characters for line numbers (default 6). 

Select the line numbering format: 
in Left justified, no leadingzeros 

rn Right justified, no leading zeros (default) 

rz Right justified, leadingzeros 

Set the two delimiter characters that indicate the beginnings of logical page sections; if only 
oneisgiven, thesecond remains:. To enter \, use \\. 

Print a usage message and exit with a nonzero status. 

Print version information on standard output, then exit. 
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nimconv— C onvert object code into an N LM 

SYNOPSIS 

nlmconv[ -Ibfd na me |--input-target=bfdname] [ -Obf dna me | 

--output-target=bfd n a me ] [ -Th eaderfilej--header-file=h e a d e r f i I e ] 

[ -V|--version ][--help ] infile outfile 

DESCRIPTION 

nimconv converts the relocatable object file mfiie into the N etW are Loadable M odule(N LM ) outfile, optionally reading 
headerf He for N LM header information. For instructions on writing the N L M command file language used in header files, 
seeTheNetWareTool M aker Specification M anual, avail able from N ovell, Inc. nimconv currently works with i 386 object files 
in COFF, ELF, ona.out format, and with SPARC object files in ELF or a.out format, nimconv uses the GN U binary file 
descriptor library to read mme. 

OPTIONS 

-i bfdname, C onsider the sourcefile'sobject format to bebfdname, rather than attempting to deduce it. 

- -input-target=bf d n a me 

-o bf dname, W rite the output fi le usi ng the object format bfdname. nimconv infers the output format 

- -output-target=bf dname based on the input format, for example, for an i 386 input file the output format is 

nlm32-i386. 



nm 



-t headerfiie. Reads header f i i e forNLM header information. For instructions on writing the N LM 

- -header-fiie=header f i i e command file language used in header files, seeTheNdWareTool M aker Specification 

Manual, availablefrom Novell, Inc. 

-v, - -version Show the version number of nimconv and exit. 

-h, - -help Show a summary of theoptionsto nimconv and exit. 

SEE ALSO 

binutiis entry in into; The GNU Binary U til i ties, Roland H. Pesch (June 1993). 

COPYING 

Copyright © 1993 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this 
manual provided thecopyright notice and this permission notice are preserved on all copies. 

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions 
for modified versions, except that this permission notice may be included in translations approved by the Free Software 
Foundation instead of in theoriginal English. 

Cygnussupport,Junel993 


nm— List symbols from object files 

SYNOPSIS 

nm [ -a|--debug-syms][-gj --extern-only ][-B ][-C J - -demangle ] 

[-D|--dynamic ][-s|--print-armap][- 0 |--print-file-name] 

[-nj--numeric-sort ][-p|--no-sort ][-r|--reverse-sort ][--size-sort ] 

[ -uj--undefined-only][--help ][--version ][-t radix]--radix=radi x ] 

[ -P ]-portability ] [ -f f or mat ] --format=f or mat ] [ --target=bf dname ][ objfile ...] 


DESCRIPTION 

GN U nm lists the symbols from object files o bj f i i e. If no object files are given as arguments, nm assumes a. out. 


OPTIONS 

The long and short forms of options, shown here as alternatives, are equivalent. 


-A, -0 

- -print-file-name 

-a, - -debug-syms 
-B 

-C, - -demangle 

-D, - -dynamic 

-f f 0 r ma t 

-g, - -extern-only 
-n, -v, - -numeric-sort 


Precede each symbol bythenameof the input file where it was found, rather than 
identifying the input file once only before all of its symbols. 

D isplay debugger-only symbols; normally these are not listed. 

The same as --format=bsd (for compatibility with theM IPS nm). 

Decode (demangle) low-level symbol namesinto user-level names. Besides removing any 
initial underscore prepended by the system, this makes C++ function names readable. 

D isplay the dynamic symbols rather than the normal symbols T his is only meaningful for 
dynamic objects, such ascertain typesof shared libraries. 

Use the output format for mat .which can bebsd, sysv, or posix. The default isbsd. 0 nly the 
first character of format is significant; it can be either uppercase or lowercase. 

D isplay only external symbols. 

Sort symbols numerically by their addresses, not alphabetically by their names. 
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-p, - -no-sort 
-P, --portability 

-s, - -print-armap 

-r, - -reverse-sort 
- -size-sort 


-t radix, - -radix=r adi x 

- -target=bf d n a me 

-u, --undefined-only 
-V, - -version 
--help 


Don't bother to sort the symbols in any order; just print them in the order encountered. 

Use the PO SIX.2 standard output format instead of the default format. Equivalent to -f 

posix. 

When listing symbols from archive members, include the index, a mapping (stored in the 
archive by ar or raniib) of which modules contain definitionsfor what names. 

Reverse the sense of the sort (whether numeric or alphabetic); let the last come first. 

Sort symbols by size. T he size is com puted as the difference between the value of the symbol 
and the value of the symbol with the next higher value. The size of the symbol is printed, 
rather than the value. 

U se radix as the radix for printing the symbol values. It must bed for decimal, o for octal, 
or x for hexadecimal. 

Specify an object codeformat other than your system's default format. Seeobjdump(l) for 
information on listing available formats. 

Display only undefined symbols(those external to each object file). 

Show the version number of ™ and exit. 

Show a summary of theoptionsto nm and exit. 


SEE ALSO 

binutiis entry in info; The GNU Binary U tilities, Roland H. Pesch (October 1991); ar(i), objdump(i), raniib(i). 

COPYING 

Copyright © 1991 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this 
manual provided thecopyright notice and this permission notice are preserved on all copies. 

Permission isgranted to copy and distribute modified versionsof thismanual under the conditions for verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 

Permission isgranted to copy and distribute translations of thismanual into another language, under the above conditions 
for modified versions, except that this permission notice may be included in translations approved by the Free Software 
Foundation instead of in the original English. 

Cygn us support, 5 N ovember!991 


nntpget 

nntpget— Get U senet articles from a remote N N T P server 

SYNOPSIS 

nntpget [ -d dist ][-f file ][-n newsgroups ][-t timestring ][-o ][-u file ][-v ] host 

DESCRIPTION 

nntpget connects to theN N TP server at the specified host and retrieves articles from it. The articles are sent to standard 
output. 

T he-o flag may be used only if the command is executed on the host where the innd(8) server is running. If this flag is used, 
nntpget connects to the specified remote host to retrieve articles. Any article not present in the local history database is then 
fetched from the remote site and offered to the local server. 

If the -v flag is used with the-o flag, then theM essage-ID of each article will be sent to standard output as it is processed. 

T he list of article M essage-l D s is normally read from standard input. If the-f flag isused, then a newnews command is used 
to retrieve all articles newer than the modification date of the specified f i i e. The -u flag is the same except that if the transfer 
succeeded, the file will be updated with a statistics line, modifying its timestamp so that it can be used in later invocations. If 
the -t flag isused, then the specified t i mestri ng isused as the time and date parameter to the newnews command. 



objcopy 

If either the-t or -t flags are used, then the-n flag may be used to specify a newsgroup list and the -d flag may be used to 
specify a distribution list. The default is* for all newsgroups, and no distribution list. 

BUGS 

T run cates articles at 512 lines. 

HISTORY 

W ritten by Rich $alz (rsaiz@uunet.uu.net) for InterNetN ews 

SEE ALSO 

innd(8) 

objcopy 

objcopy— Copy and translate object files 

SYNOPSIS 

objcopy [ -Fbfdname |--target=bfdname ] 

[ -Ibfdnamej --input-target=bf d n a me ] [ -Ob f d n a me [ 

--output-target=bf d n a me ] [ -Rs ecti onname | 

--remove-section=sect i on name ] [ -S| --strip-all ][-g J 
--strip-debug ][-x[--discard-all ][-X| 

--discard-locals][-bbyt e [--byte=byt e ] [ -ii nterl eave | 

--interleaved nterI eave ] [ -v|--verbose][-V| 

--version ][--help ] infile [ outfile ] 

DESCRIPTION 

TheGNU objcopy utility copi es the contents of an object file to another, objcopy usestheGNU BFD library to read and 
write the object files. It can write the destination object file in a format different from that of the source object file. The exact 
behavior of objcopy is controlled by command-lineoptions. 

objcopy creates temporary files to do its translation sand deletes them afterward, objcopy uses BFD to do all its translation 
work; it knows about all theformatsBFD knows about, and thus is able to recognizemostformatswithout beingtold 
explicitly. 

infiie and outfile are the source and output files, respectively. If you do not specify outfile, objcopy creates a temporary file 
and destructively renames the result with the name of the input file. 

OPTIONS 

-i bfdname, C onsider the sourcefile'sobject format to be bf dna me , rather than attemptingto deduceit. 

- -input-target=bf d n a me 

-o bfdname, W rite theoutput file using the object format bf dna me. 

- -output-target=bf dname 

-f bfdname, Usebfdname astheobject format for both the input and the output file; that is, simply 

--target=bf dna me transfer data from source to destination with no translation. 

-r sect i onname, Remove the named section from thefile. Thisoption may be given more than once N ote 

--remove-section, =s ect i onname that using this option inappropriately may make the output file unusable. 

-s, --strip-aii D o not copy relocation and symbol information from the source file. 

-g, -strip-debug D o not copy debuggi ng symbolsfrom the sourcefile. 

-x, -discard-aii D o not copy nonglobal symbolsfrom the source file. 

-x, -discard-locals Do not copy compiler-generated local symbols (These usually start with l or.). 
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-b byte, - -byte=byt e 


-i interleave, 

--interleaved nt erI eave 
-v, --verbose 

-V, --version 
--help 


Keep only every byte byte of the input file (header data is not affected), byte can be in the 
range from 0 to the interleave - 1 . This option is useful for creating files to program ROM s. 
It istypically used with an srec output target. 

Only copy one out of every interleave bytes. The one to copy is selected by the -b or 
-byte option. The default is 4 . The interleave is ignored if neither -b nor - byte is given. 

V erbose output: list all object files modified. In the case of archives, objcopy -v lists all 
members of the archive. 

Show the version number of objcopy and exit. 

Show a summary of theoptionsto objcepy and exit. 


SEE ALSO 

binutiis entry in into; TheGNU Binary U tilities, Roland H. Pesch (June 1993). 

COPYING 

Copyright © 1993 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this 
manual provided thecopyright notice and this permission notice are preserved on all copies. 

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions 
for modified versions, except that this permission notice may be included in translations approved by the Free Software 
Foundation instead of in the original English. 

Cygnus support, June 1993 


obj dump 

objdump— D isplay information from object files. 

SYNOPSIS 

objdump [ -a|--archive-headers ][-b\ bfdname J --target= bfdname ] 

[ -d|--disassemble][-D|--disassemble-all ][-f|--file-headers ] 

[ -h|--section-headers | --headers ][-i|- -info ][-j\ section 
[ --section= section ][-1|--line-numbers ][-m\ machine [ -- 
-architecture= machi ne ][-r|--reloc ][-RJ--dynamic-reloc ] 

[ -s|--full-contents ][--stabs ][-t J- -syms ] [-T| --dynamic- 
syms][-x|--all-headers ][--version ][- - help ] objfile ... 

DESCRIPTION 

objdump displays information about one or more object files. The options control what particular information to display. This 
information is mostly useful to programmers who are working on the compilation tools, as opposed to programmers who 
just want their program to compile and work. 

objfile... are the object files to be examined. When you specify archives, objdump shows information on each of the member 
object files. 

OPTIONS 

Where long and short forms of an option are shown together, they are equivalent. At least one option besides -1 (--line- 
numbers) must be given. 

-a, -archive-headers If any files from objfile are archives, display the archive header information (in a format 

similar to is - 1 ). Besides the information you could list with ar tv, objdump -a shows the 
object file format of each archive member. 
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-b bfdname, 

--target=bf d n a me 


-d, --disassemble 

-D, --disassemble-all 

-f, --file-headers 
-h, --section-headers, 

- -headers 
--help 
-i, - -info 

-j name, - -section=name 
-1, - -line-numbers 

-m mac hi ne, 

--architecture=machi ne 
-r, - -reloc 

-R, - -dynamic-reloc 

-s, --full-contents 

- -stabs 


-t, --syms 

-T, - -dynamic-syms 


- -version 

-x, - -all-headers 


Specify the object-code format for the object fi les to be bf d n a me . T his may not be necessary; 
obj dump can automatically recognize many formats. For example, objdump -b oasys -m vax - 
h tu.o displays summary information from the section headers (-h) of tu.o, which is 
explicitly identified (-m) as a Vax object file in the format produced by Oasys compilers. You 
can list theformats available with the-i option. 

D i splay the assembler mnemonics for the machine instructions from obj f i i e. This option 
only disassembles those sections that are expected to contain instructions. 

Like -d, but disassemble the contents of all sections, not just those expected to contain 
instructions. 

D isplay summary information from the overall header of each file in obj f i i e. 

D isplay summary information from the section headers of the object file. 

Printasummary of theoptionsto obj dump and exit. 

D isplay a list showing all architectures and object formats avail able for specification with -b 
or-m. 

D isplay information only for section name. 

Label the display (using debugging information) with the filename and source line numbers 
corresponding to the object code shown. Only useful with -s or -d. 

Specify the object files obj file are for architecture mac hi ne. You can list available architec¬ 
tures using the-i option. 

Print the relocation entries of the file. If used with -d or -d, the relocations are printed 
interspersed with the disassembly. 

Print the dynamic relocation entries of the file. This is only meaningful for dynamic objects, 
such ascertain types of shared libraries. 

D isplay the full contents of any sections requested. 

D isplay the contents of the .stab, .stab.index, and .stab.exci sectionsfrom an ELF file. 
This is only useful on systems (such as Solaris 2.0) in which .stab debugging symbol-table 
entries are carried in an ELF section. In most other file formats, debugging symbol-table 
entries are interleaved with linkage symbols, and are visible in the -syms output. 

Symbol table Print the symbol table entries of the file. This is similar to the information 
provided by the nm program. 

Dynamicsymbol table. Print the dynamic symbol table entries of thefile. Thisisonly 
meaningful for dynamic objects, such ascertain types of shared libraries. This is si milar to 
the information provided by the™ program when given the -d (--dynamic) option. 

Print the version number of obj dump and exit. 

Display all available header information, including thesymbol tableand relocation entries. 
Using -x isequivalentto specifyingall of -a -f -h -r -t. 


SEE ALSO 

binutiis entry in info; The GNU Binary U til i ties, Roland FI. Pesch (October 1991); nm(i). 

COPYING 

Copyright © 1991 Free Software Foundation, Inc. Permission isgranted to makeand distribute verbatim copiesof this 
manual provided thecopyright notice and this permission notice are preserved on all copies. 

Permission isgranted to copy and distribute modified versions of this manual under the conditions for verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 

Permission isgranted to copy and distribute translations of this manual into another language, under the above conditions 
for modified versions, except that this permission notice may be included in translations approved by the Free Software 
Foundation instead of in theoriginal English. 


Cygn us support, 5 N ovember!991 
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oclock 

ociock— Round X clock 

SYNOPSIS 

oclock [-option ... ] 

DESCRIPTION 

ociock simply displays the current time on an analog display. 

OPTIONS 

-fg color 
-bg color 
-jewel color 
-minute color 
-hour color 
-backing {whenMapped 
Always NotUseful} 

-geometry geomet r y 
-display display 
-bd color 
-bw width 

-shape 

-noshape 
-transparent 

COLORS 

If you would likeyour clock to be viewable in color, include the followi ng in the#ifdet color section you read with xrdb: 
*customization: -color 

This will cause ociock to pick up the colors in the app-defaults color customization file: <XRoot>/iib/xn/app-defauits/ 
ciock-coior. The default colors are 

Clock*Background Gray 

Clock*BorderColor Light blue 

Clock*hour Yellow 

Clock*jewel Yellow 

Clock*minute Yellow 

SEE ALSO 

x(l), X Toolkit documentation 

AUTHOR 

Keith Packard, M IT X Consortium 


Choose a different color for both hands and the jewel on the clock 
C hoose a different color for the background. 

C hoose a different color for the jewel on the clock. 

C hoose a different color for the minute hand of the clock. 

C hoose a different color for the hour hand of the clock. 

Select an appropriate level of backing store. 

Define the initial window geometry; seex(l). 

Specify the display to use; seex(l). 

Choose a different color for thewindow border. 

Choose a different width for the window border. As the Clock widget changes its border around 
quite a bit, this is most usefully set to zero. 

Cause the clock to use the Shape extension to create an oval window. This is the default unless the 
shapewmdow resource is set to false. 

Cause the clock to not reshape itself and ancestors to exactly fit the outline of the clock. 

Cause the clock to consist only of thejewel, the hands, and the border. 
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od 

od— D uimp fils in octal and other formats 

SYNOPSIS 

od [-abcdfhiloxv] [-s[bytes]] [-w[bytes]] [-A radix] [-j bytes] [-N bytes] 
[-t type] [--skip-bytes=bytes] [--address-radix=radix] [--read-bytes=bytes] 
[--format=type] [--output-duplicates] [--strings[=bytes]] [- - width[=bytes]] 
[--traditional] [--help] [--version] [file...] 


DESCRIPTION 

This manual page documents the GN U version of od. od writs to the standard output the contents of the given fils, or of 
the standard input if the name - is given. Each line of the output consists of the offset in the input file in the leftmost 
column of each line, followed by one or more columns of data from the file, in a format controlled by the options. By 
default, od prints the file offsets in octal and the file data as two-byte octal numbers. 


OPTIONS 

-A, --address-radix=r adi x 


-j, --skip-bytes=byt es 


-N, --read-bytes=byt es 
-t, --format=t ype 


Select the base in which fi le offsets are printed, rad i * can be one of the following: 
d Decimal 

o 0 ctal 

x Hexadecimal 

n N one (do not pri nt offsets) 

The default is octal. 

Skip bytes input bytes beforeformatting and writing. If bytes beginswith 0 x or ex, it is 
interpreted in hexadecimal; otherwise, if it beginswith 0 , in octal; otherwise, in decimal. 
Appending b multiplies it by 512, k by 1024, and m by 1048576. 

Only output up to bytes bytes of each input file. Any prefixes and suffixes on bytes are 
interpreted as for the-j option. 

Select the format in which to output the file data, type is a string of one or more of the 
following type indicator characters. If you include more than onetype indicator character in 
a singlet ype string or use this option more than once, od writes one copy of each output 
line using each of the data types that you specified, in the order that you specified, 
a N amed character 

c ASC11 character or backslash escape 

d Signed decimal 

f Floatingpoint 

0 0 ctal 

u Unsigned decimal 

x Hexadecimal 

Except for types a andc, you can specify the number of bytes to use in interpreting each 
number in thegiven data type by following thetype indicator character with a decimal 
integer. Alternately, you can specify the size of one of the C compiler's built-in data types by 
following thetype indicator character with one of the following characters. For integers (d, 

0 , u, x): 
c char 

s short 

1 int 

l long 
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-v, --output-duplicates 


-s, --strings [=bytes ] 


-w, --width[ =bytes ] 


--help 
--version 


For floating point (t): 
f float 

d double 

l long double 

0 utput consecutive lines that are identical. By default, when two or more consecutive 
output lines would be equal, od outputs only the first line, and puts just an asterisk on the 
following line to indicate that identical lines have been elided. 

Instead of the normal output, output only string constants in the input, which area run of 
at least bytes ASCII graphic (or formatting) characters, terminated byaNUL. If bytes is 
omitted, it defaults to 3 . 

T he number of input bytes to format per output line. It must be a multiple of the least 
common multiple of thesizes associated with the specified output types. If bytes isomitted, 
it defaults to 32. Ifthisoption isnot given, it defaults to 16. 

Print a usage message and exit with a nonzero status. 

Print version information on standard output, then exit. 


The next several options map the old, pre-PO SIX format specification options to the corresponding POSIX format specs. 
GN U od accepts any combination of old- and new-style options. Format specification options accumulate. 


-a 

-b 

-c 

-d 

-f 

-h 

-i 

-1 

-o 

-x 

- -traditional 


0 utput as named characters. Equivalent to -t a. 

0 utput as octal bytes. Equivalent to-t oc. 

Output as ASCI I characters or backslash escapes. Equivalent to -t c. 

Output as unsigned decimal shorts. Equivalent to -t u 2 . 

Output as floats. Equivalentto -t fF. 

Output as hexadecimal shorts. Equivalentto -t x2. 

Output as decimal shorts. Equivalentto-t d2. 

Output as decimal longs. Equivalentto -t d 4 . 

0 utput as octal shorts. Equivalentto-t 02. 

Output as hexadecimal shorts. Equivalentto -t x2. 

Recognize the pre-PO SI X nonoption arguments that some older versionsof od accepted. 
The following syntax: 

od --traditional [file] [[ + ]offset [.][b] [[+]I a be I [. ][b]]] 
can be used to specify at most one file and optional arguments specifying an offset and a 
pseudo-start address, 1 abei . By default, offset is interpreted as an octal number specifying 
how many input bytes to skip before formatting and writing. The optional trailing decimal 
point forces the interpretation of offset asadecimal number. If no decimal is specified and 
the offset begins with 0x or ax, it is interpreted as a hexadecimal number. If there is a trailing 
b, thenumber of bytes skipped will be of f s et multiplied by 512 . T he 1 a be 1 argumentis 
interpreted just like off set , but it specifies an initial pseudo-address. T he pseudo addresses 
are displayed in parentheses following any normal address. 
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passwd 

passwd— C hange password 

SYNOPSIS 


passwd [ name ] 



paste 



DESCRIPTION 

passwd changes the specified user's password. Only the superuser is allowed to change other users' passwords. If the user is 
not root, then the old password is prompted for and verified. 

A new password isprompted fortwice, to avoid typing mistakes. Unless theuser is the superuser, the new password must 
have more than six characters, and must have either both uppercase and lowercase letters, or nonletters. Some passwords that 
are similar to the user's name are not allowed. 

FILES 

/etc/passwd 

/etc/shells 

SEE ALSO 

chsh(l), chfn(l) 

BUGS 

A password consisting of all digits is allowed. 

N o warnings are printed if the superuser chooses a poor password. 

The-f and-s options are not supported. 

AUTHOR 

Peter Or baek (poe@daimi.aau.dk) 

Linux 1.0, 22 Junel994 


paste 

paste— M erge lines of files 

SYNOPSIS 

paste [-s] [-d delim-list] [--serial] [--delimiters=delim-list] [--help] 
[--version] [file...] 


DESCRIPTION 

This manual page documents the GN U version of paste, paste prints lines consisting of sequentially corresponding lines of 
each given file, separated by tabs, terminated by a newline. If no files are given, the standard input is used. A filename of - 
means standard input. 


OPTIONS 

-s, - -serial 

-d, --delimiters delim-list 


--help 
--version 


Paste the I ines of onefi le at a time rather than one line from each file 
Consecutively use the characters in deiim-iist instead of tab to separate merged lines. 
When deiim-iist isexhausted, start again at its beginning. 

Print a usage message and exit with a nonzero status. 

Print version information on standard output, then exit. 


GNU Text Utilities 
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pbmclean 

pbmciean— Flip isolated pixels in portable bitmap 

SYNOPSIS 

pbmclean [-connect] [pbmfile] 

DESCRIPTION 

pbmclean reads a portable bitmap as input and outputs a portable bitmap with every pixel that has less than connect identical 
neighbors inverted, pbmclean can be used to clean up "snow" on bitmap images. 

SEE ALSO 

pbm(5) 

AUTHOR 

Copyright© 1990 by Angus Duggan. Copyright© 1989 byjef Poskanzer. 

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is 
hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this 
permission notice appear in supporting documentation. This software is provided "as is" without express or implied 
warranty. 


pbmfilters 

pbmfiiters — List of all programsin thePBM Plus package 


DESCRIPTION 

anytopnm 

asciitopgm 

atktopbm 

bioradtopgm 

bmptoppm 

brushtopbm 

cmuwmtopbm 

fitstopnm 

fstopgm 

g3topbm 

gemtopbm 

giftopnm 

gouldtoppm 

bipstopgm 

bpcdtoppm 

icontopbm 

ilbmtoppm 

imgtoppm 

lispmtopgm 

macptopbm 

mgrtopbm 

mtvtoppm 


Attempt to convert an unknown type of image file to a portable anymap 

Convert ASCII graphics into a portable graymap 

C onvert Andrew T oolkit raster object to a portable bitmap 

Convert a Biorad confocal file into a portable graymap 

Convert a BM P file into a portable pixmap 

Convert a doodle brush file into a portable bitmap 

C onvert a C M U window manager bitmap into a portable bitmap 

C onvert a FIT S file i nto a portable anymap 

C onvert a U senix FaceSaver file into a portable graymap 

C onvert a G roup 3 fax file into a portable bitmap 

Convert a GEM IMG file into a portable bitmap 

Convert a GIF file into a portable anymap 

Convert Gould scanner file into a portable pixmap 

Convert a FI I PS file into a portable graymap 

Convert a Photo-CD file into a portable pixmap 

Convert a Sun icon into a portable bitmap 

Convert an ILBM file into a portable pixmap 

Convert an IM G-whatnot file into a portable pixmap 

Convert a Lisp machine bitmap file into PGM format 

Convert a M acPaint file into a portable bitmap 

C onvert an M G R bitmap into a portable bitmap 

Convert output from the MTV orPRT ray tracers into a portable pixmap 



pbmclean 

pbmlife 

pbmmake 

pbmmask 

pbmpscale 

pbmreduce 

pbmtext 

pbmto10x 

pbmto4425 

pbmtoascii 

pbmtoatk 

pbmtobg 

pbmtocmuwm 

pbmtoepsi 

pbmtoepsbn 

pbmtog3 

pbmtogem 

pbmtogo 

pbmtoicon 

pbmtolj 

pbmtoln03 

pbmtolps 

pbmtomacp 

pbmtomgr 

pbmtopgm 

pbmtopi3 

pbmtopk 

pbmtoplot 

pbmtoptx 

pbmtoxIBbm 

pbmtoxbm 

pbmtozinc 

pbmupc 

pcxtoppm 

pgmbentley 

pgmcrater 

pgmedge 

pgmenhance 

pgmhist 

pgmkernel 

pgmnoise 

pgmnorm 

pgmoil 

pgmramp 

pgmtexture 

pgmtofs 


pbmfilters 



Flip isolated pixels in portable bitmap 
Apply C onway's Rules of Life to a portable bitmap 
C reate a blank bitmap of a specified size 
C reate a mask bitmap from a regular bitmap 
Enlarge a portable bitmap with edge smoothing 
Read a portable bitmap and reduce it N times 
Render text into a bitmap 

Convert a portable bitmap into Gemini 10X printer graphics 

DisplayPBM images on an AT&T 4425 terminal 

Convert a portable bitmap into ASCII graphics 

Convert a portable bitmap to AndrewToolkit raster object 

Convert a portable bitmap into BitGraph graphics 

Convert a portable bitmap into aCM U window manager bitmap 

C onvert a portable bitmap into an encapsulated PostScript 

Convert a portable bitmap into Epson printer graphics 

C onvert a portable bitmap into a G roup 3 fax fi le 

Convert a portable bitmap into a GEM IMG file 

C onvert a portable bitmap into compressed G raphO n graphics 

C onvert a portable bitmap into a Sun icon 

Convert a portable bitmap into H P LaserJet format 

Convert portable bitmap to D EC LN 03+Sixel output 

Convert portable bitmap to PostScript 

Convert a portable bitmap into a M acPaintfile 

Convert a portable bitmap into an M GR bitmap 

Convert a portable bitmap to portablegraymap by averaging areas 

C onvert a portable bitmap into an Atari D egas.pi3 file 

Convert a portable bitmap into a packed (PK) format font 

C onvert a portable bitmap into a U NIX piot(5) file 

Convert a portable bitmap into Printronix printer graphics 

C onvert a portable bitmap into an X10 bitmap 

Convert a portable bitmap into an Xll bitmap 

Convert a portable bitmap into a Zinc bitmap 

C reate a U niversal Product C ode bitmap 

Convert a PCX file into a portablepixmap 

Bentleyize a portable graymap 

C reate cratered terrai n by fractal forgery 

Edge-detect a portable graymap 

Edge-enhance a portable graymap 

Print a histogram ofthevaluesin a portable graymap 

Generate a convolution kernel 

C reate a graymap madeup of white noise 

N ormalize the contrast in a portable graymap 

T urn a portable graymap into an oil painting 

G enerate a grayscale ramp 

Calculate textural features on a portable graymap 

C onvert a portable graymap to U senix FaceSaver format 
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pgmtolispm 

pgmtopbm 

pgmtoppm 

pgmtoybm 

piltoppm 

pi3topbm 

picttoppm 

pjtbppm 

pktbpbm 

pnraalias 

pnmarith 

pnmcat 

pnmcomp 

pnmconvol 

pnmcrop 

pnracut 

pnmdepth 

pnmenlarge 

pnmfile 

pnmflip 

pnmgamma 

pnmhistmap 

pnmindex 

pnminvert 

pnmmargin 

pnmnlfilt 

pnmnoraw 

pnmpad 

pnmpaste 

pnmrotate 

pnrascale 

pnmshear 

pnmsmooth 

pnmtile 

pnmtoddif 

pnmtofits 

pnmtops 

pnmtorast 

pnmtosgi 

pnmtosir 

pnmtotiff 

pnmtoxwd 

ppm3d 

ppmbrighten 

ppmchange 

ppmdim 


Convert a portable graymap into Lisp machine format 
C onvert a portable graymap into a portable bitmap 
Colorize a portable graymap into a portable pi xmap 
Convert a portable bitmap into a Bennet Yee"face" file 
C onvert an Atari D egas PI 1 into a portable pixmap 
Convert an Atari Degas PI 3 file into a portable bitmap 
Convert a M acintosh PICT fileinto a portable pixmap 
Convert an HP PaintJet file into a portable pixmap 
Convert packed (PK) format font into portable bitmap(s) 

Anti alias a portable anymap 
Perform arithmetic on two portable anymaps 
C oncatenate portable anymaps 
C omposite two portable anymap files together 
General mxn convolution on a portable anymap 
Crop a portable anymap 
C ut a rectangle out of a portable anymap 
Change the maxvai in a portable anymap 
Read a portable anymap and enlarge it N times 
D escri be a portable anymap 

Perform one or more flip operationson a portable anymap 

Perform gamma correction on a portable anymap 

D raw a histogram for a PGM or PPM file 

Build a visual index of a bunch of anymaps 

Invert a portable anymap 

Add a border to a portable anymap 

Nonlinear filters: smooth, alpha trim mean, optimal 

Force a portable anymap into plain format 

Add borders to portable anymap 

Paste a rectangle i nto a portable anymap 

Rotate a portable anymap by some angle 

Scale a portable anymap 

Shear a portable anymap by some angle 

Smooth out an image 

Replicate a portable anymap into a specified size 

C onvert a portable anymap to D DIF format 

Convert a portable anymap into FITS format 

C onvert portable anymap to PostScript 

Convert a portable pixmap into a Sun raster file 

C onvert a portable anymap to an SGI i mage fi le 

Convert a portable anymap into a Solitaire format 

Convert a portable anymap into aTIFF file 

Convert a portable anymap into an Xll window dump 

Convert two portable pixmap into a red/blue 3D glasses pixmap 

Change an images Saturation and Value from an HSV map 

Change all pixels of one color to another in a portable pixmap 

Dima portable pixmap down to total blackness 



pbmfilters 



ppmdist 

ppmdither 

ppmflash 

ppmforge 

ppmhist 

ppmmake 

ppramix 

ppmnorm 

ppmntsc 

ppmpat 

ppmquant 

ppmquantall 

ppmqvga 

ppmrelief 

ppmshift 

ppmspread 

ppmtoacad 

ppmtobmp 

ppmtogif 

ppmtoicr 

ppmtoilbm 

ppmtomap 

ppmtomitsu 

ppmtopcx 

ppmtopgm 

ppmtopil 

ppmtopict 

ppmtopj 

ppmtopjxl 

ppmtopuzz 

ppmtorgb3 

ppmtosixel 

ppmtotga 

ppmtouil 

ppmtoxpm 

ppmtoyuv 

ppmtoyuvsplit 

psidtopgm 

pstopnm 

qrttoppm 

rasttopnm 

rawtopgm 

rawtoppm 

rgb3toppm 

sgitopnm 

sirtopnm 


Simplistic grayscale assignment for machine generated, color images 

Ordered dither for color images 

Brighten a pictureup to complete white-out 

Fractal forgeries of clouds planets, and starry skies 

Print a histogram of a portable pixmap 

C reate a pixmap of a specified size and color 

B lend together two portable pixmaps 

N ormalizethecontrast in a portable pixmap 

M ake a portable pixmap look like it was taken from an American TV show 
M ake a pretty pixmap 

Quantize the colors in a portable pixmap down to a specified number 
Run ppmquant on a bunch of files all at once, so they share a common colormap 
8 -plane quantization 

Run a Laplacian relief filter on a portable pixmap 

Shift lines of a portable pixmap left or right by a random amount 

D isplace a portable pixmap's pixels by a random amount 

Convert portable pixmap to AutoCAD database or slide 

Convert a portable pixmap into a BM P file 

C onvert a portable pixmap into a GIF file 

Convert a portable pixmap into NCSA ICR format 

Convert a portable pixmap into an I LB M file 

Extract all colors from a portable pixmap 

Convert a portable pixmap to a M itsubishi S340-10 file 

Convert a portable pixmap into a PCX file 

C onvert a portable pixmap into a portable gray map 

Convert a portable pixmap into an Atari Degas PI 1 file 

Convert a portable pixmap into a M acintosh PICT file 

Convert a portable pixmap to an FI P PaintJet file 

Convert a portable pixmap into an FI P PaintJet XL PC L file 

Convert a portable pixmap into an Xll "puzzle'' file 

Separate a portable pixmap into three portable graymaps 

Convert a portable pixmap into DEC sixel format 

Convert portable pixmap into aTrueVision Targafile 

Convert a portable pixmap into a M otif UIL icon file 

Convert a portable pixmap into an Xll pixmap 

Convert a portable pixmap into an Abekas YU V file 

Convert a portable pixmap into three subsampled raw YUV files 

Convert PostScript "image" data into a portablegraymap 

Convert a PostScript file into a portable anymap 

C onvert output from the 0 RT ray tracer into a portable pixmap 

C onvert a Sun raster file into a portable anymap 

C onvert raw grayscale bytes into a portable graymap 

C onvert raw RGB bytes into a portable pixmap 

C ombine three portable graymaps into one portable pixmap 

Convert an SGI image file into a portable anymap 

Convert a Solitaire file into a portable anymap 
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sldtoppm 

spctoppm 

spottopgm 

sputoppm 

tgatoppm 

tifftopnm 

xbmtopbm 

ximtoppm 

xpmtoppm 

xvminitoppm 

xwdtopnm 

ybmtopbm 

yuvplittoppm 

yuvtoppm 

zeisstopnm 


Convert an AutoCAD slide file into a portable pixmap 

C onvert an Atari compressed Spectrum file into a portable pixmap 

Convert SPOT satellite images to Portable Graymap format 

Convert an Atari uncompressed Spectrum file into a portable pixmap 

C onvert T rueVision T arga file into a portable pixmap 

Convert aTIFF fileinto a portableanymap 

Convert an Xll or X10 bitmap into a portable bitmap 

C onvert an XIM fi le into a portable pixmap 

Convert an Xll pixmap into a portable pixmap 

Convert an XV thumbnail picture to PPM 

Convert an Xll or X10 window dump file into a portable anymap 

Convert a Bennet Yee"face" fileinto a portable bitmap 

Convert a Y-, U- and V-fileinto a portable pixmap 

C onvert Abekas YU V bytes into a portable pixmap 

C on vert a Z ei ss confocal fi le i nto a portabl e anymap 


SEE ALSO 

anytopnm(l), asciitopgm(l), atktopbm(l), bioradtopgm(l), bmptoppm(l), brushtopbm(l), cmuwmtopbm(l), fitstopnm(l), fstopgm(l), 
g3topbm(l), gemtopbm(l), giftopnm(l), gouldtoppm(l), hipstopgm(l), hpcdtoppm(l), icontopbm(l), ilbmtoppm(l), imgtoppm(l), 
lispmtopgm(l), macptopbm(l), mgrtopbm(l), mtvtoppm(l), pbmclean(l), pbmlife(l), pbmmake(l), pbmmask(l), pbmpscale(l), 
pbmreduce(l), pbmtext(l), pbmto10x(l), pbmto4425(l), pbmtoascii(l), pbmtoatk(l), pbmtobbnbg(l), pbmtocmuwm(l), pbmtoepsi(l), 
pbmtoepson(l), pbmtog3(l), pbmtogem(l), pbmtogo(l), pbmtoicon(l), pbmtolj(l), pbmtoln03(l), pbmtolps(l), pbmtomacp(l), 
pbmtomgr(l), pbmtopgm(l), pbmtopi3(l), pbmtopk(l), pbmtoplot(l), pbmtoptx(l), pbmtox10bm(l), pbmtoxbm(l), pbmtoybm(l), 
pbmtozinc(l), pbmupc(l), pcxtoppm(l), pgmbentley(l), pgmcrater(l), pgmedge(l), pgmenhance(l), pgmhist(l), pgmkernel(l), 
pgmnoise(l), pgmnorm(l), pgmoil(l), pgmramp(l), pgmtexture(l), pgmtofs(l), pgmtolispm(l), pgmtopbm(l), pgmtoppm(l), 
piltoppm(l), pi3topbm(l), picttoppm(l), pjtoppm(l), pktopbm(l), pnmalias(l), pnmarith(l), pnmcat(l), pnmcomp(l), pnraconvol(l), 
pnracrop(l), pnmcut(l), pnmdepth(l), pnmenlange(l), pnmfile(l), pnmflip(l), pnmgamina(l), pnmhistmap(l), pnmindex(l), 
pnminvertf 1), pnmmargin(l), pnmnlfilt(l), pnranoraw(l), pnmpad(l), pmpaste(l), pnmrotate(l), pnmscale(l), pnmshean(l), 
pnmsmooth(l), pnmtile(l), pnmtoddif(l), pnmtofits(l), pnmtops(l), pnmtorast(l), pnmtosgi(l), pnmtosir(l), pnmtotiff(1), 
pnmtoxwd(l), ppm3d(l), ppmbrighten(l), ppmchange(l), ppmdim(l), ppmdist(l), ppmdither(l), ppmflash(l), ppmforge(l), 
ppmhist(l), ppmmake(l), ppmmix(l), ppmnorm(l), ppmntsc(l), ppmpat(l), ppmquant(l), ppmquantall(l), ppmqvga(l), ppmrelief(1), 
ppmshift(l), ppmspread(l), ppmtoacad(l), ppmtobmp(l), ppmtogif(l), ppmtoicr(l), ppmtoilbm(l), ppmtomap(l), ppratomitsufl), 
ppmtopcx(l), ppmtopgm(l), ppmtopil(l), ppmtopict(l), ppmtopj (1), ppmtopjxl(l), ppmtopuzz(l), ppmtorgb3(l), ppmtosixel(l), 
ppmtotga(l), ppmtouil(l), ppmtoxpm(l), ppmtoyuv(l), ppmtoyuvsplit(l), psidtopgm(l), pstopnm(l), qrttoppm(l), rasttopnm(l), 
rawtopgm(l), rawtoppm(l), rgb3toppm(l), sgitopnm(l), sirtopnm(l), sldtoppm(l), spctoppm(l), spottopgm(l), sputoppm(l), 
tgatoppm(l), tifftopnm(l), xbmtopbin(l), ximtoppm(l), xpmtoppm(l), xvniinitoppm(l), xwdtopnm(l), nybmtopbm(l), 
yuvsplittoppm(l), yuvtoppm(l), zeisstopnm(l) 


AUTHORS 

Many. Seethe individual manual pages. 


pbmlife 

pbmiife— Apply Conway's Rules of Life to a portable bitmap 

SYNOPSIS 

pbmlife [pbmf i I e ] 



pbmmask 



DESCRIPTION 

pbmiife reads a portable bitmap as input, applies the Rules of Life to it for one generation, and produces a portable bitmap as 
output. 

A white pixel in the image is interpreted as a live beastie, and a black pixel as an empty space. 

SEE ALSO 

pbm(5) 

AUTHOR 

Copyright © 1988,1991 byjef Poskanzer 

21 February 1991 


pbmmake 

pbmmake — C reate a blank bitmap of a specified size 

SYNOPSIS 

pbmmake [-white!-black|-gray ] width height 

DESCRIPTION 

pbmmake produces a portable bitmap of the specified width and height. The color defaults to white. 

OPTIONS 

In addition to the usual -white and -black, thisprogram implements -gray. T hisgivesa simple 50 percent gray pattern with 
l's and 0's alternating. 

All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

pbm(5), ppmmake(l) 

AUTHOR 

Copyright© 1989 byjef Poskanzer 

22 February 1989 


pbmmask 

pbmmask— C reate a mask bitmap from a regular bitmap 

SYNOPSIS 

pbmmask [ - expand] [pbmf i I e ] 

DESCRIPTION 

pbmmask reads a portable bitmap as input and creates a corresponding mask bitmap and writes it out. 

The color to be interpreted as background is determined automatically. Regardless of which color is background, the mask 
will be white where the background is white and black where thefigure is black. 
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This lets you do a masked paste like this for objects with a black background: 
pbmmask obj > objmask 

pnmpaste < dest -and objmask <x><y>|pnmpaste -or obj <x><y> 

For objects with a white background, you can either invert them or add a step: 
pbmmask obj > objmask 

pnminvert objmask j pnmpaste -and obj 0 0 > blackback 

pnmpaste < dest -and objmask <x><y>|pnmpaste -or blackback <x><y> 

N ote that this three-step version works for objects with black backgrounds, too, if you don't care about the wasted time 

You can also usemaskswith graymapsand pixmaps, using the pnmarith tool. For instance 

ppmtopgm obj.ppm | pgmtopbm -threshold j pbmmask > objmask.pbm 
pnmarith -multiply dest.ppm objmask.pbm > tl.ppm 
pnminvert objmask.pbm \ pnmarith -multiply obj.ppm - > t2.ppm 
pnmarith -add tl.ppm t2.ppm 

An interesting variation on this is to pipe the mask through thepnmsmooth script before using it. This makes the boundary 
between thetwo images less sharp. 

OPTIONS 

-expand Expands the mask by one pixel out from the image. T his is useful if you want a little white border around your 
image. (A better solution might beta turn thepbmiife tool into a general cellular automaton tool...) 

SEE ALSO 

pnmpaste(l), pnminvert(l), pbm(5), pnmarith(l), pnmsmooth(l) 

AUTHOR 

Copyright© 1988 byjef Poskanzer 

8 August 1989 


pbmpscale 

pbmpscaie— Enlarge a portable bitmap with edge smoothing 

SYNOPSIS 

pbmpscale N [ pbmf i I e ] 

DESCRIPTION 

pbmpscale reads a portable bitmap as input and outputs a portable bitmap enlarged N times. Enlargement is done by pixel 
replication, with some additional smoothing of corners and edges. 

SEE ALSO 

pnmenlarge(l), ppmscale(l), pbm(5) 

AUTHOR 

Copyright© 1990 by Angus Duggan. Copyright© 1989 byjef Poskanzer. 

NOTES 

pbmpscale works best for enlargements of 2. Enlargements greater than 2 should be done by as many enlargements of 2 as 
possible, followed by an enlargement by the remaining factor. 



pbmtext 



pbmreduce 

pbmreduce — Read a portable bitmap and reduce it N times 

SYNOPSIS 

pbmreduce [ -floydj - f s |-threshold ] [ - value v a I ] N [pbmfile] 

DESCRIPTION 

pbmreduce reads a portable bitmap as input, reduces it by a factor of n, and produces a portable bitmap as output. 

pbmreduce duplicates a lot Of thefUnCti0nality Of pgmtopbm; you could do something like pnmscale | pgmtopbm, but pbmreduce 
is a lot faster. 

pbmreduce can be used to "re-halftone'' an image. Say you have a scanner that only produces black and white, not grayscale, 
and it does a terrible job of halftoni ng (most black-and-white scanners fit this description). 0 ne way to fix the halftoning is 
to scan at the highest possible resolution, say 300dpi, and then reduce by a factor of three or so using pbmreduce. You can even 
correct the brightness of an image, by using the -value flag. 

OPTIONS 

By default, the halftoning after the reduction is done via boustrophedonic Floyd-Steinberg error diffusion; however, the - 
threshold flag can beusedto specify simplethresholding.Thisgives better results when reducing line drawings. 

The - value flag alters thethresholding value for all quantizations It should be a real number between 0 and 1. Above 0.5 
means darker images; below 0.5 means lighter. 

All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

pnmenlarge(l), pnmscale(l), pgmtopbm(l), pbm(5) 

AUTHOR 

Copyright© 1988 byjef Poskanzer 

2 August 1989 


pbmtext 

pbmtext— Render text into a bitmap 

SYNOPSIS 

pbmtext [-font fontfi I e][-builtin f ont name ] [t ext ] 

DESCRIPTION 

pbmtext takes the specified text, either a single line from the command line or multiple lines from standard input, and renders 
it into a bitmap. 

OPTIONS 

By default, pbmtext uses a built-in font called bdf (about a 10-point Times Roman font). You can use a fixed-width font by 
Specifying -builtin fixed. 

You can also specify your own font with the -font flag. The fontfi i e is either a BDF file from theX Window System or a 
PBM file 
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If the f ontf i i e is a P BM file, it is created in a very specific way. In your window system of choice, display the following text 
in the desired (fixed-width) font: 

m V" 1 1 :pqyI m 
/ !"#$%&'()*+ / 

< ,-./01234567 < 

> 89:;<=>?@ABC > 

@ DEFGHIJKLMNO @ 

PQRSTUVWXYZ [ 

{ \]" 1 abcdefg { 

} hijklmnopqrs } 
tuvwxyz{|}" 

M ',/' [ 1 jpqyI M 

Do a screen grab or window dump of that text, using for instance xwd, xgrabsc, or screen-dump. Convert the result into a 
PBM file If necessary, usepnmcut to remove everything except the text. Finally, run it through pnmcrop to makesurethe 
edges are right up against the text, pbmtext can figure out the sizes and spacingsfrom that. 

SEE ALSO 

pbm(5), pnmcut(l), pnmcrop(l) 

AUTHOR 

Copyright© 1993 byjef Poskanzer and George Phillips 

26 October 1993 


pbmtol0x 

pbmtoiox— C on vert a portable bitmap into G emini 10X printer graphics 

SYNOPSIS 

pbmto10x [-h] [pbmfi I e ] 

DESCRIPTION 

pbmtoiox reads a portable bitmap as input and produces a file of Gemini 10X printer graphics as output. The 10X 'sprinter 
codes are alleged to be similar to theEpson codes. 

Notethatthereisno lextopbm tool; thistransformation isone-way. 

OPTIONS 

T he resolution is normally 60H by 72V . If the h flag is specified, resolution is 120H by 144V. You may find it useful to 
rotate landscape images before printing. 

SEE ALSO 

pbm(5) 

AUTHOR 

Copyright © 1990 by Ken Yapl 


January 1990 



pbmtoasrii 
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pbmto4425 

pbmto442s— D isplay PBM images on an AT&T 4425 terminal 

SYNOPSIS 

pbmto4425 [pbmf i I e ] 

DESCRIPTION 

Pbmto4425 displays PBM format images on an AT&T 4425 ASCII terminal using that terminal's mosaic graphics character 
set. The program should also work with other VT100-1 ike terminals with mosaic graphics character sets such as the C. Itoh 
C IT-101, but it has not yet been tested on terminals other than the 4425. 

Pbmto4425 puts the terminal into 132-column mode to achieve the maximum resolution of theterminal. In thismodethe 
terminal has a resolution of 264 columns by 69 rows. The pixel shave an aspect ratio of 1:2.6; therefore an image should be 
processed before being displayed in a manner such as this: 

% pnmscale -xscale 2.6 pnmfile \ 

| pnmscale -xysize 264 69 \ 

| ppmtopgm \ 

| pgmtopbm \ 

] pbmto4425 

AUTHOR 

Copyright © 1993 by Robert Perlberg 

pbmtoascii 

pbmtoascii— Convert a portable bitmap into ASCII graphics 

SYNOPSIS 

pbmtoascii [-1x2]-2x4] [pbmf i I e ] 

DESCRIPTION 

pbmtoascii reads a portable bitmap as input and produces a somewhat crude ASCI I graphic as output. 

N ote that there is no asciitopbm tool; this transformation is oneway. 

OPTIONS 

The -ix 2 and - 2 x 4 flags provide two alternate ways for the bits to get mapped to characters. W ith 1 x 2 , the default, each 
character represents a group of 1 bit across by 2 bits down. With - 2 x 4 , each character represents 2 bits across by 4 bits down. 
With the 1 x 2 mode you can see the individual bits, so it’s useful for previewing small bitmaps on a nongraphics terminal. 
The 2x4 mode lets you display larger bitmaps on a standard 80-column display, but it obscures bit-level details. 2 x 4 mode is 
also good for displayi ng graymaps. pnmscale -width 158 j pgmnorm ] pgmtopbm -thresh should give good results. 

SEE ALSO 

pbm(5) 

AUTHOR 

Copyright© 1988,1992 byjef Poskanzer 


20 March 1992 
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pbmtoatk 

pbmtoatk — C onvert portable bitmap to Andrew T oolkit raster object 

SYNOPSIS 

pbmtoatk [pbmf i I e ] 

DESCRIPTION 

pbmtoatk reads a portable bitmap as input and produces an Andrew T oolkit raster object as output. 

SEE ALSO 

atktopbm(l), pbm(5) 

AUTHOR 

Copyright © 1991 by Bill Janssen 

26 September 1991 


pbmtobg 

pbmtobg— Convert a portable bitmap into BitGraph graphics 

SYNOPSIS 

pbmtobg [rasterop][x y]< pbmfile 

DESCRIPTION 

pbmtobg reads a portable bitmap as input and produces BBN BitGraph terminal display pixel data (D PD) sequence as output. 

Therasterop can be specified on thecommand line. If this is omitted, 3 (replace) will beused. A position in (x,y) coordi¬ 
nates can also be specified. If both are given, therasterop comes first. The portable bitmap is always taken from the standard 
input. 

Notethatthereisno bgtopbm tool. 

SEE ALSO 

pbm(5) 

AUTHOR 

C opyright © 1989 by M ike Parker 

16 May 1989 


pbmtocmuwm 

pbmtocmuwm— Convert a portable bitmap into aCM U window manager bitmap 

SYNOPSIS 

pbmtocmuwm [pbmf i I e ] 

DESCRIPTION 

pbmtocmuwm reads a portable bitmap as input and produces a CM U window manager bitmap as output. 



pbmtoepson 



SEE ALSO 

cmuwmtopbm(l), pbm(5) 

AUTHOR 

Copyright© 1989 byjef Poskanzer 

15 April 1989 


pbmtoepsi 

pbmtoepsi— Convert a portable bitmap into an encapsulated PostScript-style preview bitmap 

SYNOPSIS 

pbmtoepsi [-bbonly][pbmf i I e] 

DESCRIPTION 

pbmtoepsi reads a portable bitmap as input and produces an encapsulated PostScript-style bitmap as output. The output is 
not a standalone PostScript file; it is only a preview bitmap, which can be included in an encapsulated PostScript file. N ote 
that there is no epsitopbm tool; thistransformation isone-way. 

This utility isa part of thepstoepsi tool by Doug Crabill (dgc@cs.purdue.edu). 

OPTIONS 

-bboniy 0 nly create a boundary box, don'tfill it with the image. 

SEE ALSO 

pbm(5), pnmtops(l), psidtopgm(l) 

AUTHOR 

Copyright © 1988 byjef Poskanzer, modified by Doug Crabill 1992 

1992 


pbmtoepson 

pbmtoepson— Convert a portable bitmap into Epson printer graphics 

SYNOPSIS 

pbmtoepson [pbmf i I e] 

DESCRIPTION 

pbmtoepson reads a portable bitmap as input and produces a file of Epson printer graphics as output. 
N ote that there is no epsontopbm tool; thistransformation isone-way. 

SEE ALSO 

pbm(5) 

AUTHOR 

Copyright © 1991 by John Tiller (tiiier@gaiois.msfc.nasa.gov) and Jef Poskanzer 


4 January 1991 
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pbmtog3 

pbmtog3— C onvert a portable bitmap into a G roup 3 fax file 

SYNOPSIS 

pbmtog3 [pbmf i I e ] 

DESCRIPTION 

pbmtog3 reads a portable bitmap as output and produces a Group 3 fax file as input. 

REFERENCES 

The standard for Group 3 fax is defined in CCITT Recommendation T.4. 

BUGS 

Probably. 

SEE ALSO 

g3topbm(l), pbm(5) 

AUTHOR 

Copyright© 1989 by Paul Haeberli (<paui@manray.sgi.com>) 

2 October 1989 

pbmtogem 

pbmtogem— Convert a portable bitmap into a GEM IMG file 

SYNOPSIS 

pbmtogem [pbmf i I e ] 

DESCRIPTION 

pbmtogem reads a portable bitmap as input and produces a compressed GEM IMG file as output. 

BUGS 

pbmtogem does not support compression of repeated lines. 

SEE ALSO 

gemtopbm(l), pbm(5) 

AUTHORS 

Copyright © 1988 by D avid Beckemeyer and Jef Poskanzer 

11 July 1992 

pbmtogo 

pbmtogo— C onvert a portable bitmap into compressed GraphOn graphics 

SYNOPSIS 

pbmtogo [pbmf i I e ] 



pbmtolj 



DESCRIPTION 

pbmtogo reads a portable bitmap as input and produces 2D compressed GraphO n graphics as output. Be sure to set up your 
GraphOn with the following modes: 8 bits/no parity; obeys no XON/XOFF; nuls are accepted. These are all on the Comm 
menu. Also, remember to turn off tty post processing. N ote that there is no gotopbm tool. 

SEE ALSO 

pbm(5) 

AUTHORS 

Copyright© 1988,1989 byjef Poskanzer, M ichael Haberler, and BoThide 

24 N ovember 1989 


pbmtoicon 

pbmtoicon— C onvert a portable bitmap into a Sun icon 

SYNOPSIS 

pbmtoicon [pbmf i I e ] 

DESCRIPTION 

pbmtoicon reads a portable bitmap as input and produces a Sun icon as output. 

SEE ALSO 

icontopbm(l), pbm(5) 

AUTHOR 

Copyright© 1988 byjef Poskanzer 

31 August 1988 


pbmtolj 

pbmtoij — Convert a portable bitmap into FI P LaserJet format 

SYNOPSIS 

pbmtolj [-resolution N][-float][-noreset][pbmf i I e] 

DESCRIPTION 

pbmtoij reads a portable bitmap as input and produces FI P LaserJet data as output. 

Notethatthereisno ljtopbm tool. 

OPTIONS 

-resolution Specifies the resolution of the output device in dpi. Typical values are 75 , 100 , 150 , 300 . The default is 75 . 

-float Suppresses positioning information. T he default isto write the sequence esc & 1 0 e to the output file, 

-noreset Prevents pbmtoij from writing the reset sequences to the beginning and end of the output file. 

All flags can be abbreviated to their shortest unique prefix. 


SEE ALSO 

pbm(5) 
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AUTHORS 

Copyright © 1988 by Jef Poskanzer and M ichael Haberler. -float and -noreset optionsadded by Wim Lewis 

29 August 1988 


pbmtoln03 

pbmtoin03— Convert portable bitmap to D EC LN 03+Sixel output 

SYNOPSIS 

pbmtoln03 [-rltbf] pbmfile 

DESCRIPTION 

pbmtoin03 reads a portable bitmap as input and produces a D EC LN 03+Sixel output file. 

OPTIONS 

-i nn Usenn asvaluefor left margin (default 0 ). 

-r nn Usenn asvaluefor right margin (default 2400 ). 

-t nn Usenn as value for top margin (default 0 ). 

-b nn Usenn as value for bottom margin (default 3400). 

-f nn Usenn as value for form length (default 3400 ). 

SEE ALSO 

pbm(5) 

AUTHOR 

Tim Cook, 26 February 1992 

7 May 1993 


pbmtolps 

pbmtoips— C onvert a portable bitmap to PostScript 

SYNOPSIS 

pbmtolps [ -dpi n ] [ pbmfiIe ] 

DESCRIPTION 

pbmtolps reads a portable bitmap as input, and outputs PostScript. The output PostScript uses lines instead of the image 
operator to generate a (device-dependent) picture that will be imaged much faster. 

The PostScript path length is constrained to be less that 1000 points so that no limits are overrun on the Apple LaserWriter 
and (presumably) no other printers. 

SEE ALSO 

pgmtops(l), ppmtops(l), pbm(5) 

AUTHOR 

G eorge Phillips (<phniips@cs. ubc .ca>) 



pbmtomgr 



pbmtomacp 

pbmtomacp— C onvert a portable bitmap into a M acPaint file 

SYNOPSIS 

pbmtomacp [-1 I eft ] [ - r r i g h t ] [ - b bottom][-t top][pbmfi I e] 

DESCRIPTION 

pbmtomacp reads a portable bitmap as input. If no input file is given, standard input is assumed. Produces a M acPaint file as 
output. 

The generated file is only the data fork of a picture. You will need a program such asmcvert to generate a M acbinary or a 
BinH ex file that contains the necessary information to identify the file as a PNTG file to M acOS. 

OPTIONS 

Left, ri ght, bottom, and top let you defi ne a square i nto thePBM file, which must be converted. D efault is the whole file. If 
the file is too large for a M acPaint file the bitmap is cut to fit from (i eft, top). 

BUGS 

The source code contains comments in a language other than English. 

SEE ALSO 

ppmtopict(l), macptopbm(l), pbm(5), mcvert(l) 

AUTHOR 

Copyright © 1988 by D ouwevan der Schaaf <... tmcvaxtuvapsytvdschaaf) 

31 August 1988 


pbmtomgr 

pbmtomgr— Convert a portable bitmap into an MGR bitmap 

SYNOPSIS 

pbmtomgr [pbmf i I e ] 

DESCRIPTION 

pbmtomgr reads a portable bitmap as input and produces an M G R bitmap as output. 

SEE ALSO 

mgrtopbm(l), pbm(5) 

AUTHOR 

Copyright© 1989 byjef Poskanzer 


24 January 1989 
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pbmtopgm 

pbmtopgm— C onvert portable bitmap to portable graymap by averaging areas 

SYNOPSIS 

pbmtopgm <width><height> [pbmfile] 

DESCRIPTION 

pbmtopgm reads a portable bitmap as input and outputs a portable graymap created by averaging the number of pixels within a 
sample area of width by height around each point, pbmtopgm is similar to a special case of ppmconvoi. A ppmsmooth step may be 
needed after pbmtopgm. 

pbmtopgm has the effect of antialiasing bitmaps that contain distinct line features. 

SEE ALSO 

pbm(5) 

AUTHOR 

Copyright© 1990 by Angus Duggan. Copyright© 1989 byjef Poskanzer. 

NOTES 

pbmtopgm works best with odd sample widths and heights. 

pbmtopi3 

pbmtopi3— Convert a portable bitmap into an Atari Degas PI 3 file 

SYNOPSIS 

pbmtopi3 [pbmfile] 

DESCRIPTION 

pbmtopi3 reads a portable bitmap as input and produces an Atari Degas PI 3 file as output. 

SEE ALSO 

pi3topbm(l), pbm(5), ppmtopil (1), piltoppm(l) 

AUTHOR 

Copyright© 1988 byDavidBeckemeyer(bdtmavid) andJefPorkanzer. 

11 March 1990 



pbmtopk 

pbmtopk— C onvert a portable bitmap into a packed (PK) format font 

SYNOPSIS 


pbmtopk pkfile[.pk] tfmfile[.tfm] resolution [-s designsize] [-p num param...] 
[-C cod-ingscheme] [-F family] [-f optfile] [-c num] [-W width] [-H height] 

[-D depth] [-1 ital] [-h horiz] [-v vert] [-x xoff] [-y yoff] [pbmfile]... 



pbmtoplot 
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DESCRIPTION 

pbmtopk reads portable bitmaps as in put and produces a packed (PK) font file and aTFM (TeX font metric) file as output. 

The resolution parameter indicates the resolution of the font, in dots per inch. If the filename - is used for any of the 
filenames, the standard input stream (or standard output, where appropriate) will be used. 

OPTIONS 

-s des i g ns i z e Sets the design size of the font, in T eX's poi nts (72.27 pointsto the inch). T he default design size is i. The 
TFM parameters are given as multiples of the design size. 

-p nura pa r a m ... Sets the first num font parameters for the font. T he first seven parameters are the slant, interword spacing, 
interword sp ace stretch ab i I i ty, interword space shrinkability, x-height, quad width, and post-sentence extra 
space of the font. M ath and symbol fonts may have more parameters; see The TeX book for a list of these. 
Reasonable default values are chosen for parameters that are not specified. 

-c codi ngscheme Sets the coding scheme comment in theT FM file. 

-f family Sets the font family comment in theT FM file. 

-f optf i i e Readsthefileo ptf i i e, which should contain alineof theform: 

filename xoff yoff horiz vert width height depth ital 

ThePBM files specified by thefilename parameters areinserted consecutively in thefontwith the 
specified attributes. If any of the attributes are omitted, or replaced with *, a default value will be 
calculated from the size of the bitmap. The settings of the -w, -h, -d, -i, -h, -v, -x, and -y options do not 
affect characters created in this way. The character number can be changed by including a line starting 
with =, followed by the new number. Lines beginning with %or# are ignored. 

-c num Sets the character number of thenext bitmap encountered to num. 

-w width SetstheTFM width of the next character to wi dth (in design size multiples). 

-h height SetstheTFM height ofthe next character to height (in design size multi pies). 

-d depth SetstheTFM depth of the next character to depth (in design size multiples). 

-i itai Setsthe italic correction of the next character to i t a i (in design size multiples). 

-h horiz Sets the horizontal escapement of the next character to horiz (in pixels). 

- v vert Sets the vertical escapement of the next character to mt (in pixels). 

-x xoff Sets the horizontal offset of the next character to xoff (in pixels). 

-y yoff Sets the vertical offset of the next character to yoff (in pixels, from thetop row). 

SEE ALSO 

pktopbm(l), pbm(5) 

AUTHOR 

Adapted from T om Rokicki ’s pxtopk by Angus Duggan (ajcd@dcs.ed.ac.uk). 

6 August 1990 

pbmtoplot 

pbmtoplot— C onvert a portable bitmap into a U N IX piot(5) file 

SYNOPSIS 

pbmtoplot [pbmf i I e ] 

DESCRIPTION 

pbmtoplot readsa portable bitmap asinput and producesa U N IX plot file. 

N otethat there is no piottopbm tool; this transformation is one way. 



Parti: User Commands 



SEE ALSO 

pbm(5), plot(5) 

AUTHOR 

Copyright © 1990 by Arthur D avid 0 Ison. 

1 September 1990 


pbmtoptx 

pbmtoptx— Convert a portable bitmap into Printronix printer graphics 

SYNOPSIS 

pbmtoptx [pbmf i I e ] 

DESCRIPTION 

pbmtoptx reads a portable bitmap as input and produces a file of Printronix printer graphics as output. 

N ote that there is no ptxtopbm tool; this transformation is one-way. 

SEE ALSO 

pbm(5) 

AUTHOR 

Copyright© 1988 byjef Poskanzer 

31 August 1988 


pbmtoxl0bm 

pbmtoxiiabm— Convert a portable bitmap into an X10 bitmap 

SYNOPSIS 

pbmtoxl0bm [pbmf i I e ] 

DESCRIPTION 

pbmtoxl 0 bm reads a portable bitmap as input and produces an X10 bitmap as output. This older format is maintained for 
compatibility. 

Notethat there is no xiebmtopbm tool because xbmtopbm can read bothXll andXlO bitmaps. 

SEE ALSO 

pbmtoxbm(l), xbmtopbm(l), pbm(5) 

AUTHOR 

Copyright© 1988 byjef Poskanzer. 


31 Auguil988 
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pbmtoxbm 

pbmtoxbm— Convert a portable bitmap into an Xll bitmap 

SYNOPSIS 

pbmtoxbm [pbmf i I e ] 

DESCRIPTION 

pbmtoxbm reads a portable bitmap as input and produces an Xll bitmap as output. 

SEE ALSO 

pbmtox10bm(l), xbmtopbm(l), pbm(5) 

AUTHOR 

Copyright© 1988 byjef Poskanzer. 

31 August 1988 


pgmtoybm 

pgmtoybm— Convert a portable bitmap into a Bennet Yee"face" file 

SYNOPSIS 

pbmtoybm [pbmf i I e ] 

DESCRIPTION 

pgmtoybm reads a portable bitmap as input and produces as output a file acceptable to thetace and xbm programs by Bennet 
Yee(bsy+@cs. cmu.edu). 

SEE ALSO 

ybmtopbm(l), pbm(5), face(l), face(5), xbm(l) 

AUTHORS 

Copyright© 1991 byJamieZawinski andJef Poskanzer. 

6 March 1990 


pbmtozinc 

pbmtozinc— C on vert a portable bitmap into a Zinc bitmap 

SYNOPSIS 

pbmtozinc [pbmf i I e ] 

DESCRIPTION 

pbmtozinc reads a portable bitmap as input and produces a bitmap in the format used by the Zinc Interface Library (ZIL) 
version 1.0 as output. 


SEE ALSO 

pbm(5) 
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AUTHORS 

Copyright © 1988 by James Darrel I M cCauley (jdm5548@diamond.tamu.edu) and J ef Poskanzer. 


2 N ovember 1990 


pbmupc 

pbmupc — C reate a U niversal Product C ode bitmap 

SYNOPSIS 

pbmupc [ - s 1 j -s 2 ] type manufac product 

DESCRIPTION 

pbmupc generates a Universal Product Code symbol. The three arguments are: a one-digit product type, a five-digit manufac¬ 
turer code, and a five-digit product code. For example, 0 72890 00011 isthecodefor H eineken. 

As presently configured, pbmupc produces a bitmap 230 bits wide and 175 bits high. The size can be altered by changing the 
defines at the beginning of the program, or by running the output through pnmeniarge or pnmscaie. 

OPTIONS 

The -si and -s 2 flags select the style of UPC to generate. The default, -si, looks more or less like this: 


12345! 


67890 


Theother style, -s 2 , puts the product type digit higher up, and doesn't display the checksum digit: 


12345 


67890 


SEE ALSO 

pbm(5) 

AUTHOR 

Copyright© 1989 by J ef Poskanzer. 


14 March 1989 


pcxtoppm 

pcxtoppm— Convert a PCX file into a portable pi xmap 

SYNOPSIS 

pcxtoppm[p c x f i I e] 

DESCRIPTION 

pcxtoppm reads a PCX file as input and produces a portable pixmap as output. 


































pgmbentley 



SEE ALSO 

ppmtopcx(l), ppm(5) 

AUTHOR 

C opyright © 1990 by M ichael D avidson. 

9 April 1990 


pfbtops 

pfbtops— Translate a PostScript font in PFB format to ASCII 

SYNOPSIS 

pfbtops [ pfb_fiIe ] 

DESCRIPTION 

pfbtops translates a PostScript font in PFB format to ASCII. I f pf b_f tie is omitted, thePFB file will be read from the 
standard input. TheASCII format PostScript font will be written on thestandard output. PostScript fonts forM S-DOS are 
normally supplied in PFB format. 

The resulting ASCII format PostScript font can be used with groff. It must first be listed in /usr/iib/groff/font/devps/ 
download. 


SEE ALSO 

grops(l) 


Groff Vers on 1.09, 6 August 1992 


pgmbentley 

pgmbentley— Bentleyize a portable graymap 

SYNOPSIS 

pgmbentley [pgmfile] 

DESCRIPTION 

pgmbentley reads a portable graymap as input, performs the Bentley Effect, and writes a portable graymap as output. 

The Bentley Effect is described in Be/ond Photography by FI olzmann, Chapter 4, photo 4. It's a vertical smearing based on 
bri ghtness. 

SEE ALSO 

pgmoil(l), ppmrelief(l), pgm(5) 

AUTHOR 

Copyright © 1990 by W iIson Bent (whb@hoh- 2 .att.com). 


11 January 1991 
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pgmcrater 

pgmcrater — C reate cratered terrain by fractal forgery 

SYNOPSIS 

pgmcrater [-number n ][-height|-ysize s][-widthj-xsize s][-gamma g] 

DESCRIPTION 

pgmcrater creates a portable graymap that mimics cratered terrain. The graymap is created by simulating the impact of a 
given number of craters with random position and size then rendering the resulting terrain elevations based on a light source 
shining from one side of the screen. The size distribution of the craters is based on a power law that results in many more 
small craters than large ones. The number of craters of a given size varies as the reciprocal of the area as described on pages 31 
and 32 of The Science Of Fractal Images edited by H .0. Peitgen and D. SaupefN ew York: Spri nger-V erlag, 1988). Cratered 
bodies in the solar system are observed to obey this relationship. The formula used to obtain crater radii governed by this law 
from a uniformly distributed pseudorandom sequence was developed by Rudy Rucker. 

H igh resolution images with large numbers of craters often benefit from being piped through pnmsmooth. The averaging 
performed by thisprocesseliminatessomeof thejagged pixelsand lendsamellow "telescopic image" feel to theoveralI 
picture. 

OPTIONS 

-number n Causes n craters to be generated. If no -number specification is given, 50,000 craterswill be generated. Don't 
expect to see them all! For every large crater, there are many, many more tiny ones that tend simply to erode the landscape. 

In general, the more craters you specify, the more realistic the result; ideally, you want the entire terrain to have been 
extensively turned over again and again by cratering. H igh-resolution images containing five to ten million craters are 
stunning but take quite a while to create. 

-height height Sets the height of the generated image to he i ght pixels. The default height is 256 pixels. 

-width width Sets the width of the generated image to wi dt h pixels. The default width is 256 pixels. 

-xsize width Sets the width of the generated image to wi dt h pixels. The default width is 256 pixels. 

-ysize height Sets the height of the generated image to hei ght pixels. The default height is 256 pixels. 

-gamma factor The specified factor isused to gamma correct the graymap in the same manner as performed by pnmgamma. 

The default value is i . 0 , which results in a medium contrast image. Values larger than 1 lighten the image 
and reduce contrast, while values less than 1 darken the image, increasing contrast. 

All flags can be abbreviated to their shortest unique prefix. 

BUGS 

The -gamma option isn't really necessary because you can achieve the same effect by piping the output from pgmcrater 
through pnmgamma. H owever, pgmcrater performs an internal gamma map anyway in the process of rendering the elevation 
array into a graymap, so there's no additional overhead in allowing a user-specified gamma. 

Real craters have two distinct morphologies, pgmcrater simulates only small craters, which are hemispherical in shape 
(regardless of the incidence angle of the impacting body, as long as the velocity is sufficiently high). Large craters, such as 
Copernicus and T ycho on the moon, have a "walled plain" shape with a cross-section more like: 

/\/\ 

_ / \ _ /\ _ / \ _ 

Larger craters should really use this profile, including the central peak, and totally obliterate the preexisting terrai n. 

SEE ALSO 

pgm(5), pnmgamma(l), pnmsmooth(l) 
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AUTHOR 

John Walker 

Autodesk SA Avenue des C hamps-M ontants 14b 
CH-2074 MARIN 

Sui sse 1 Sch wei z/ Svi zzera/ Svizra/ Swi tzerl an d 
Usenet: kelvin@Autodesk.com 

Fax: 038/33 88 15 

Voice 038/33 76 33 

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is 
hereby granted, without any conditions or restrictions. This software is provided "as is" without express or implied warranty. 

PLUG WARE! If you like this kind of stuff, you may also enjoyJamesGleick's "Chaos—The Software" for M S-DOS, 
available for $59.95 from your local software store or directly from Autodesk, Inc., Attn: Science Series, 2320 M arinship 
Way, Sausalito, CA 94965, U SA. Telephone: 800-688-2344 toll-free or, outside the U.S. (415) 332-2344 Ext 4886. Fax: 
415-289-4718. "C haos—The Software" includes a more comprehensive fractal forgery generator that creates three- 
dimensional landscapes as wel I as clouds and planets, plus five more modules that explore other aspects of C haos. T he user 
guide of more than 200 pages includes an introduction byJamesGleick and detailed explanations by Rudy Rucker of the 
mathematics and algorithms used by each program. 

15 October 1991 


pgmedge 

pgmedge — Edge detect a portable graymap 

SYNOPSIS 

pgmedge [pgmfile] 

DESCRIPTION 

pgmedge reads a portable graymap as input, outlines the edges, and writes a portable graymap as output. Pi ping the result 
through pgmtopbm -threshold and playing with the threshold value will give a bitmap of the edges. 

The edge detection techniqueused isto take the Pythagorean sum of two Sobel gradient operators at 90 degrees to each 
other. For more details see Digital ImageProcesng by Gonzalez and Wintz, Chapter 7. 

SEE ALSO 

pgmenhance(l), pgmtopbm(l), pgm(5), pbm(5) 

AUTHOR 

Copyright© 1991 byjet Poekanzer. 

4 February 1990 


pgmenhance 

pgmenhance— Edgeenhancea portable graymap 

SYNOPSIS 

pgmenhance [ -N ] [pgmf i I e ] 
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DESCRIPTION 

pgmenhance reads a portable graymap as input, enhances the edges, and writes a portable graymap as output. 

Theedge enhancing technique i s taken from Philip R. Thompson'sxim program, which took it from section 6 of Digital 
H alftonesby Dot Diffusion, D. E. Knuth, ACM Transaction on Graphics]/ ol. 6, N o. 4, October 1987, which in turn got it 
from two 1976 papers by J. F. Jarviset. al. 

OPTIONS 

The optional -n flag should be a digit from 1 to 9.1 isthe lowest level of enhancement, 9 isthe highest; the default is 9. 

SEE ALSO 

pgmedge(l), pgm(5), pbm(5) 

AUTHOR 

Copyright© 1989 byjef Poskanzer. 

13 January 1989 


pgmhist 

pgmhist — Print a histogram of the values in a portable graymap 

SYNOPSIS 

pgmhist [ p g mf i I e ] 

DESCRIPTION 

pgmhist reads a portable graymap as input and prints a histogram of the gray values. 

SEE ALSO 

pgmnorm(l), pgm(5), ppmhist(l) 

AUTHOR 

Copyright© 1989 byjef Poskanzer 

28 February 1989 


pgmkernel 

pgmkernei— Generate a convolution kernel 

SYNOPSIS 

pgmkernel [ -weight w ] width [ height ] 

DESCRIPTION 

pgmkernel generates a portable graymap array of sizewidth x height (or width x width ifheight is not specified) to be used as 
a convolution file by pnmconvoi. The data in the convolution array K are computed according to the formula: 

K0.il=- 1 
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wherew is a coefficient specified via the -weight flag, and width andheight aretheX and Y filter sizes. 

Theoutput PGM file is always written out in ASCII format. 

OPTIONS 

Theoptional -weight flag should beareal number greater than -1. The default value is6.a. 

BUGS 

The computation time is proportional to width * height. This increases rapidly with the increase of the kernel size. A better 
approach could beto usea FFT in these cases. 

SEE ALSO 

pnmconvol(l), pnmsmooth(l) 

AUTHOR 

Alberto Accornazzi (alberto@cfa.harvard.edu) 

10 December 1992 


pgmnoise 

pgmnoise — C reate a graymap made up of white noise 

SYNOPSIS 

pgmnoise width height 

DESCRIPTION 

pgmnoise creates a portable graymap that is made up of random pixels with gray values in the range of 0 to pgm_maxmaxval 
(depends on the compilation, either 255 or 65535 ). The graymap has a size of width * height pixels. 

SEE ALSO 

pgm(5) 

AUTHOR 

Copyright © 1993 by Frank N eumann 

16 N ovember 1993 


pgmnorm 

pgmnorm— N ormalizethecontrast in a portable graymap 

SYNOPSIS 

pgmnorm[-bpercent N | -bvalue N][-wpercent N j -wvalue N][pgmfi I e] 

DESCRIPTION 

pgmnorm reads a portable graymap as input; normalizes the contrast by forcing the lightest pixels to white, the darkest pixels to 
black, and li nearly rescaling the ones in between; and produces a portable graymap as output. 

OPTIONS 

By default, the darkest two percent of all pixels are mapped to black, and the lightest one percent are mapped to white. You 
can override these percentages by using the - bpercent and -wpercent flags, or you can specify the exact pixel values to be 
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mapped by using the -bvaiue and -wvaiue flags. Appropriate numbers for the flags can begotten from thepgmhist tool. If 
you just want to enhance the contrast, then choose values at elbows in thehistogram; for example, if value 29 represents3 
percent of the image but value 30 represents20 percent, choose 30 for bvaiue. If you want to lighten the image, then set 
bvaiue to 0 and just fiddlewith wvaiue; similarly, to darken theimage, set wvaiue to maxvai and play with bvaiue. 

All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

pgmhist(l), ppmnonm(l), pgm(5) 

AUTHOR 

Partially based on the fbnorm filter in M ichael M auldin's "Fuzzy Pixmap” package. 

Copyright® 1989 byjef Poskanzer. 

28 February 1989 


pgmoil 

pgmoii— Turn a portablegraymap into an oil painting 

SYNOPSIS 

pgmoil [-n N ] [pgmf i I e ] 

DESCRIPTION 

pgmoii reads a portable graymap as input, does an "oil transfer,” and writes a portable graymap as output. 

The oil transfer is described in Beyond Photography by H olzmann, Chapter 4, photo 7. It's a sort of localized smearing. 

OPTIONS 

T he optional -n flag controls the size of the area smeared. T he default value is 3 . 

BUGS 

T akesa long time to run. 

SEE ALSO 

pgmbentley(l), ppmrelief(l), pgm(5) 

AUTHOR 

Copyright® 1990 by Wilson Bent(whbohoh- 2 . att.com). 

11 January 1991 


pgmramp 

pgmramp — G enerate a grayscale ramp 

SYNOPSIS 

pgmramp -lr|-tb j -rectangle!-ellipse width height 

DESCRIPTION 

pgmramp generates a graymap of the specified si ze containing a black-to-white ramp. These ramps are useful for multiplying 
with other images, using the pnmarith tool. 
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OPTIONS 

-ir A left to right ramp 

-tb A top to bottom ramp 

-rectangle A rectangular ramp 

-ellipse An elliptical ramp 

All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

pnmarith(l), pgm(5) 

AUTHOR 

Copyright© 1989 byjef Poskanzer. 

24 N ovember 1989 


pgmtexture 

pgmtexture— Calculate textural features on a portable gray map 

SYNOPSIS 

pgmtexture [ -d d][pgmf i I e] 

DESCRIPTION 

pgmtexture reads a portable graymap as input. Calculates textural features based on spatial dependence matrices at 0, 45, 90, 
and 135 degrees for a distanced (default = i).Textural features include 

(1) Angular Second M oment 

(2) Contrast 

(3) Correlation 

(4) Variance 

(5) InverseD ifference M oment 

(6) Sum Average 

(7) Sum Variance 

(8) Sum Entropy 

(9) Entropy 

(10) D ifferenceVariance 

(11) D ifference Entropy 

(12,13) Information M easures of Correlation 
(14) M aximal Correlation Coefficient 

Algorithm taken from "Textural Features for I mage Classification," IEEE Transactions on Systems, Man, and Cybertinetics, 

R.M . H aralick, K. Shanmugam, and I. D instein, 1973. SM C-3(6):610-621. 

BUGS 

Theprogram can run incredibly slowly for large images (larger than 64x64) and command-lineoptionsarelimited. The 
method for finding the maximal correlation coefficient, which requires finding the second largest eigenvalue of a matrix Q, 
does not always converge. 

REFERENCES 

IEEE Transactionson Systems M an, and Cybertinetics SM C-3(6):610-621. 
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SEE ALSO 

pgm(5), pnmcut(l) 

AUTHOR 

Copyright© 1991 by Texas Agricultural Experiment Station, employer-for-hireof James Darrell M cCauley. 

22 August 1991 


pgmtofs 

pgmtofs— C onvert portable graymap to U senix FaceSaver format 

SYNOPSIS 

pgmtofs [ p g mf i I e ] 

DESCRIPTION 

pgmtofs reads a portable graymap as input. Produces U senix FaceSaver format as output. 

FaceSaver isa registered trademark of M etron Computerware Ltd. of Oakland, CA. 

SEE ALSO 

fstopgm(l), pgm(5) 

AUTHOR 

Copyright© 1991 byjef Poskanzer. 

18 May 1990 


pgmtolispm 

pgmtoiispm— Convert a portable graymap into Lisp machineformat 

SYNOPSIS 

pgmtolispm [pgmfile] 

DESCRIPTION 

pgmtolispm reads a portable graymap as input and produces a Lisp machine bitmap as output. 

This is the file format read by the tv: read-bit-array-file function on TI Explorer and Symbolics Lisp machines. 

Given a PGM (instead of a PBM ), a multiplane image will be output. This is probably not useful unless you have a color 
Lisp machine. 

M ultiplane bitmaps on Lisp machines are color; buttheiispm image file format does not include a colormap, so it must be 
treated as a graymap instead. This is unfortunate. 

SEE ALSO 

lispmtopgm(l), pgm(5) 

BUGS 

Output width is always rounded up to the nearest multiple of 32; this might not always be what you want, but it probably is 
(arrays that are not modulo 32 cannot be passed to theiispm bitblt function, and thus cannot easily be displayed on the screen). 

N o color. 
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AUTHOR 

Copyright © 1991 byJamieZawinski and Jef Poskanzer. 


6 March 1990 


pgmtopbm 

pgmtopbm— C onvert a portable graymap into a portable bitmap 

SYNOPSIS 

pgmtopbm [-floyd|-fsj-threshold |-hilbert |-dither8|-d8J-cluster3 
|-c3j-cluster4j-c4 j-cluster8|-c8][-value val ][- clump si ze][pgmf i I e] 

DESCRIPTION 

pgmtopbm reads a portable graymap as input and produces a portable bitmap as output. 

N ote that there is no pbmtopgm converter because any pgm program can read PBM files automagically. 

OPTIONS 

The default quantization method is boustrophedonic Floyd-Steinberg error diffusion (-fioyd or -ts). Also available are 
simple thresholding (-threshold); Bayer's ordered dither (-dithers) with a 16x16 matrix; and three different sizes of 45- 
degree clustered-dot dither (-clusters, -cluster^ -clusters). A space-filling curve halftoning method using the H ilbert 
curveisalso available, (-hilbert). 

Floyd-Steinberg will almost always give the best looking results; however, looking good is not always what you want. For 
instance, thresholding can be used in a pipeline with thepnmconvoi tool, for tasks like edge and peak detection. And 
clustered-dot dithering gives a newspaper-like look, a useful special effect. The - value flag alters the thresholding value for 
Floyd-Steinberg and simple thresholding. It should be a real number between 0 and 1. Above 0.5 means darker images; 
below 0.5 means lighter. 

The FI ilbert curve method is useful for processing images before display on devices that do not render individual pixels 
distinctly (like laser printers). This dithering method can give better results than the dithering usually done by the laser 
printers them selves. The - clump flag alters the number of pixels in a clump. This is usually an integer between 2 and 100 
(defaults). Smaller clump sizes smear the image less and are less grainy, but seem to loose some grayscale linearity. Typically, 
a PGM image will have to be scaled to fit on a laser printer page (2400 x 3000 pixels for an A4 300dpi page), and then 
dithered to a PBM image before being converted to a PostScript file. A printing pipeline might look something like this: 

pnmscale -xysize 2400 3000 image.pgm | pgmtopbm -hil | pnmtops -scale 0.25 image.ps 

All flags can be abbreviated to their shortest unique prefix. 

REFERENCES 

The only reference you need for this stuff is Digital H alftoning by Robert U lichney, M IT Press, ISBN 0-262-21009-6. 

The FI ilbert curve space filling method is taken from "D igital H alftoning with Spacefilling Curves" by LuizVelho, 
ComputerGraphicsVo\ume25, Number4, proceedingsofSIGRAPH '91, page81. ISBN 0-89791-436-8 

SEE ALSO 

pbmreduce(l), pgm(5), pbm(5), pnmconvol(l), pnmscale(l), pnmtops(l) 

AUTHOR 

Copyright© 1989 by J ef Poskanzer. 


26 July 1988 
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pgmtoppm 

pgmtoppm— Colorize a portable graymap into a portable pixmap 

SYNOPSIS 

pgmtoppm col or spec [pgmfile] 
pgmtoppm col orspecl -col orspec2 [pgmfile] 
pgmtoppm -map mapfile [pgmfile] 

DESCRIPTION 

pgmtoppm reads a portable graymap as input, colorizes it by multiplying the gray values by specified color or colors, and 
produces a portable pixmap as output. 

If only one color is specified, black in the PGM file stays black and white in the PGM file turns into the specified color in 
the PPM file. If two colors (separated by a hyphen) are specified, then black gets mapped to the first color and white gets 
mapped to the second. 

Thecolorcan be specified in five ways: 

■ A name, assuming that a pointer to an X 11-style color namesfilewascompiled in. 

■ An X 11-style hexadecimal specifier: ngb: r/g/b, where r, g, and b are each 1- to 4-digit hexadecimal numbers. 

■ An X 11-style decimal specifier: rgbi: r/g/b, where r, g, and b are floating-point numbers between 0 and 1. 

■ For backwards compatibility, an old-X 11-style hexadecimal number: #rgb, #mggbb, #mrgggbbb, or#mmggggbbbb. 

■ For backwards compatibility, a triplet of numbers separated by commas: r,g,b, where r, g, and b are floating-point 
numbers between 0 and 1. (This style was added before M IT came up with the similar rgbi style) 

Also, the -map flag lets you specify an entire colormap to be used. The mapfile is just a PPM file; it can beany shape all that 
matters is the colors in it and their order. In this case, black gets mapped to the first color in the mapfile, and white gets 
mapped to the last. 

SEE ALSO 

rgb3toppm(l), ppmtopgm(l), ppmtorgb3(l), ppm(5), pgm(5) 

AUTHOR 

Copyright© 1991 byjef Poskanzer. 

11 January 1991 


piltoppm 

piitoppm— Convert an Atari Degas PI 1 into a portablepixmap 

SYNOPSIS 

piltoppm [pi IfiI e ] 

DESCRIPTION 

piitoppm reads an Atari D egas P11 f i le as i n put and produ ces a portabl e pi xmap as output. 

SEE ALSO 

ppmtopil(l), ppm(5), pi3topbm(l), pbmtopi3(l) 

AUTHORS 

Copyright© 1991 by Steve Belczyk (seb3@gte.com) and J ef Poskanzer. 


19 July 1990 
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pi3topbm 

pi3topbm— Convert an Atari D egas PI 3 file into a portable bitmap 

SYNOPSIS 

pi3topbm [pi 3f iI e ] 

DESCRIPTION 

pi3topbm reads an Atari Degas PI3 file as input. Produces a portable bitmap as output. 

SEE ALSO 

pbmtopi3(l), pbm(5), piltoppm(l), ppmtopil(1) 

AUTHORS 

Copyright® 1988 by David Beckemeyer (bdtidavid) and D iomidisD. Spinellis. 

11 March 1990 


picttoppm 

picttoppm — C onvert a M acintosh PICT file into a portable pixmap 

SYNOPSIS 

picttoppm [-verbose][-fullres][-noheader][-quickdraw][-fontdirf i I e] [pict fiIe ] 


DESCRIPTION 

picttoppm reads a PICT file (version 1 or 2) and outputs a portable pixmap. Useful as the first step in converting a scanned 
image to something that can bedisplayed on U NIX. 


OPTIONS 

-fontdir file 

-fullres 

-noheader 

-quickdraw 

-verbose 


M ake the list of BDF fonts in fi i e available for use by pict-toppm when drawing text. For the format of 
the fontdir file see the "fontdir FileFormat" subsection. 

Force any images in the PICT file to be output with at least their full resolution. A PICT file may indicate 
that a contained image isto be scaled down before output. This option forces images to retain thei r sizes 
and prevent information loss. Use of this option disables all PICT operations except images. 

Do not skip the 512-byte header that is present on all PICT files. This is useful when you have PICT data 
that was not stored in the data fork of a PICT file. 

Execute only pure quickdraw operations In particular, turn off the interpretation of special PostScript 
printer operations. 

T urns on verbose mode, which prints a whole bunch of information that only picttoppm hackers really 
care about. 


BUGS 

ThePICT fileformatisa general drawing format, picttoppm does not support all the drawing commands, but it does have 
full support for any image commands and reasonable support for line, rectangle, polygon, and text drawing. It is useful for 
converting scanned images and some drawing conversion. 

M emory is used very liberally with at least six bytes needed for every pixel. Large bitmap PICT files will likely run your 
computer out of memory. 
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fontdir FILE FORMAT 

picttoppm hasabuilt-in default font and your local installer probably provided adequate extra fonts. You can point picttoppm 
at more fonts that you specify in a font directory file. Each line in the file is either a comment line, which must begin with #, 
or font information. The font information consists of four whitespace separated fields. The first is the font number, the 
second isthefontsizein pixels thethird isthe font style andthefourth isthenameof aBDF filecontainingthefont. The 
BDF format is defined bytheX Window System and isnot described here. 

The font number indicates the type face. H ere is a list of known font numbers and their faces. 

0 Chicago 

1 Application font 

2 N ew York 

3 G eneva 

4 M onaco 

5 Venice 

6 London 

7 Athens 

8 San Francisco 

9 T oronto 

11 Cairo 

12 LosAngeles 

20 Times Roman 

21 Helvetica 

22 Courier 

23 Symbol 

24 Taliesin 

The font style indicates a variation on the font. M ulti pie variations may apply to a font and the font style is the sum of the 
variation numbers, which are 

1 Boldface 

2 Italic 

4 Underlined 

8 Outlined 

is Shadow 

32 Condensed 

64 Extended 

Obviously, the font definitions are strongly related to theM acintosh. M ore font numbers and information about fonts can 
be found in M acintosh documentation. 



SEE ALSO 

Inside M acintosh volumes 1 and 5, ppmtopict(l), ppm(5) 

AUTHOR 

Copyright ©1993 George Phillips 


29 N ovember 1991 
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pjtoppm 

pjtoppm— Convert an HP PaintJ et file to a portable pixmap 

SYNOPSIS 

pjtoppm [pai ntj et ] 

DESCRIPTION 

pjtoppm reads an H P PaintJet file as input and converts it into a portable pixmap. This was a quick hack to save some trees, 
and it only handles a small subset of the paint jet commands. In particular, it will only handle enough commands to convert 
most raster image files. 

REFERENCES 

HP PaintJetXL Color Graphics Printer U ser'sGuide 

SEE ALSO 

ppmtopj (1) 

AUTHOR 

C opyright© 1991 by C hristos Zoulas. 

14 July 1991 


pktopbm 

pktopbm— C onvert packed (PK) format font into portable bitmap(s) 

SYNOPSIS 

pktopbm pkfile[.pk] [-c num] pbmfile ... 

DESCRIPTION 

pktopbm reads a packed (PK) font file as input and produces portable bitmaps as output. If the filename"-" is used for any of 
thefilenames, the standard input stream (or standard output where appropriate) will beused. 

OPTIONS 

-c num Sets the character number of the next bitmap written to num. 

SEE ALSO 

pbmtopk(l), pbm(5) 

AUTHOR 

Adapted from T om Rokicki ’s pxtopk by Angus D uggan (ajcd@dcs.ed.ac.uk). 

6 August 1990 

pnmalias 

pnmalias— Antialias a portable anymap. 

SYNOPSIS 


pnmalias [-bgcolor col or ][-fgcolor col or ][-bonly][-fonly][-balias][-falias] 
[ - weight w] [pnmf i I e ] 
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DESCRIPTION 

pnmaiias reads a portable anymap as i nput and applies antialiasing to background and foreground pixels. If the input file is a 
portable bitmap, the output antialiased image is promoted to a graymap, and a message is printed informing the user of the 
change in format. 

OPTIONS 

-bgcolor col orb, Set the background color to col orb, and the foreground to color to col or f . Pixels with these values 

-fgcoior col or f will be antialiased. By default, the background color is taken to be black, and foreground color is 

assumed to be white. The colors can be specified in five ways: 

■ A name, assuming that a pointer to an X 11-style color namesfilewascompiled in. 

■ An X 11-style hexadecimal specifier: rgb: r/g/b, where r, g, and b are each 1- to 4-digit 
hexadecimal numbers. 

■ An X 11-style decimal specifier: rgbi: r/g/b, wherer, g, and b are floating-point numbers 
between 0 and 1. 

■ For backwards compatibility, an old-X 11-style hexadecimal number: #rgb, #rrggbb, 
#rrrgggbbb, Or #rrrrggggbbbb. 

■ For backwards compatibility, a triplet of numbers separated bycommas: r,g,b, wherer, g, 
and b are floating-point numbers between 0 and 1. (Thisstyle was added beforeM IT came 
up with thesimilar rgbi style) 

N otethat a/en when dealing with graymaps, background and foreground colors need to be specified in the fashion described 
in the preceding list. In this case, background and foreground pixel values are taken to be the value of the red component for 
the given color. 

-boniy, -toniy Apply antialiasi ng only to background (-boniy), or foreground (-tonly) pixels. 

-baiias, -talias Apply antialiasing to all pixels surrounding background (-baiias), or foreground (-taiias) pixels. 

By default, antialiasing takes place only among neighboring background and foreground pixels, 
-weight w Usew as the central weight for the aliasing filter, w must be a real number in the range 0 <w <1. 

The lower the value of w is, the "blurrier" the output i mage is. The default is w = 1 / 3 . 

SEE ALSO 

pbmtext(l), pnmsmooth(l), pnm(5) 

AUTHOR 

Copyright© 1992 by Alberto A ccomazzi, Smithsonian Astrophysical Observatory. 

30 April 1992 

pnmarith 

pnmarith — Perform arithmetic on two portable anymaps 

SYNOPSIS 

pnmarith -addj-subtractj-multiply[-difference pnmf i I el pnmf i I e2 

DESCRIPTION 

pnmarith reads two portable anymaps as input, performs the specified arithmetic operation, and produces a portable anymap 
as output. The two input anymaps must be the same width and height. 

The arithmetic is performed between corresponding pixels in the two anymaps, as if maxvai wasi . 0 , black was 0 . 0 , with a 
linear scalein between. Results that fall outside of [ 0 .. 1 ) are truncated. 




pnmcomp 



The operator -difference calculates the absolute value of 
pnmarith -subtract pnmfilel pnm- f i I e2 
In other words, no truncation is done. 

All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

pbmmask(l), pnmpaste(l), pnminvert(l), pnm(5) 

AUTHOR 

Copyright© 1989,1991 byjef Poskanzer. Lightly modified by M arcel W ijkstra (wijkstra@fwi.uva.ni). 

26 August 1993 


pnmcat 

pnmcat — C oncatenate portable anymaps 

SYNOPSIS 

pnmcat [-white!-black] -leftright|-lr [-jtop|-jbottom] pnmfile pnmfile ... 
pnmcat [-white!-black] -topbottom!-tb [-jleft|-jright] pnmfile pnmfile ... 

DESCRIPTION 

pnmcat reads portable anymaps as input, concatenates them either left to right or top to bottom, and produces a portable 
anymap as output. 

OPTIONS 

If the anymaps are not all the same height (left-right) or width (top-bottom), the smaller ones have to be justified with the 
largest. By default, they get centered, but you can specify one side or the other with one of the - j * flags. So, -topbottom - 
j left would stack the anymaps on top of each other, flush with the left edge. 

The -white and -black flags specify which colorto use to fill in the extra space when doing thisjustification. If neither is 
specified, the program makes a guess. 

All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

pnm(5) 

AUTHOR 

Copyright© 1989 byjef Poskanzer. 

12 March 1989 


pnmcomp 

pnmcomp— Composite two portable anymap files together 

SYNOPSIS 

pnmcomp [-invert][-xoffN] [ -yoffN] [-alphapgmfile] overlay [pnm- i nput ][pnm- out put ] 
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DESCRIPTION 

pnmcomp reads in a portable anymap image and puts an overlay upon it, with optional alpha mask. The -aiphapgmtiie allows 
you to also add an alpha mask file to the compositing process; the range of max and min can be swapped by using the - invert 
option. The -xoft and -yoff arguments can be negative, allowing you to shift the overlay off the top corner of the screen. 

SEE ALSO 

pnm(5) 

AUTHOR 

Copyright© 1992 by David Koblas (kobias@mips.com). 

21 February 1989 


pnmconvol 

pnmconvoi— General mxn convolution on a portable anymap 

SYNOPSIS 

pnmconvol convol uti onfi I e [pnmfile] 

DESCRIPTION 

pnmconvol reads two portable anymapsas input, convolves the second using the first, and writes a portable anymap as output. 

Convolution means replacing each pixel with a weighted average of the nearby pixels. The weights and the area to average are 
determined by the convolution matrix. The unsigned numbersin the convolution fi le are offset by -maxvai /2 to makesigned 
numbers, and then normalized, so the actual values in theconvolution file are only relative. 

H ere is a sample convolution file; it does a simple average of the nine immediate neighbors, resulting in a smoothed image 

P2 
3 3 
18 

10 10 10 
10 10 10 
10 10 10 

T o see how this works, do the offset mentioned in the preceding paragraph: 10 -18/2 gives 1. The possible range of values is 
from 0 to 18, and after the offset that's-9 to 9. The normalization step makes the range-1 to 1, and the values get scaled 
correspondingly so they become 1/9— exactly what you want. The equivalent matrix for 5x5 smoothing would havemaxvai 
50 and be filled with 26 . 

Theconvolution file will usually be a graymap, so that the same con volution is applied to each color component. H owever, if 
you want to use a pixmap and do a different convolution to different colors, you can certainly do that. 

SEE ALSO 

pnmsmooth(l), pnm(5) 

AUTHOR 

Copyright© 1989,1991 byjef Poskanzer. 


13 January 1991 
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pnmcrop 

pnmcrop — C rop a portable anymap 

SYNOPSIS 

pnmcrop [-white]-black][-left][-right][-top][-bottom][pnmf i Ie] 

DESCRIPTION 

pnmcrop reads a portable anymap as input, removes edges that are the background color, and produces a portable anymap as 
output. 

OPTIONS 

By default, it makes a guess as to what the background color is. You can override the default with the -white and -black flags. 

The options -left, -right, -top and -bottom restrict cropping to the sides specified. The default isto crop all sides of the 
image. 

All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

pnmcut(l), pnm(5) 

AUTHOR 

Copyright© 1989 byjef Poskanzer. 

25 February 1989 


pnmcut 

pnmcut — C ut a rectangle out of a portable anymap 

SYNOPSIS 

pnmcut x y width height [pnmfile] 

DESCRIPTION 

pnmcut reads a portable anymap as input, extracts the specified rectangle, and produces a portable anymap as output. The x 
and y can be negative in which case they are interpreted relative to the right and bottom of the anymap, respectively. 

SEE ALSO 

pnm(5) 

AUTHOR 

Copyright© 1989 byjef Poskanzer. 

21 February 1989 


pnmdepth 

pnmdepth— Change the maxvai in a portable anymap 

SYNOPSIS 


pnmdepth newmaxval [pnmfile] 
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DESCRIPTION 

pnmdepth reads a portable anymap as input, scales all the pixel values, and writes out the image with the new maxvai. Scaling 
the colors down to a smaller maxvai will result in some loss of information. 

Be careful of off-by-one errors when choosing the new maxvai. For instance if you want the color values to be five bits wide, 
use a maxvai Of 31, not 32. 

SEE ALSO 

pnm(5), ppmquant(l), ppmdither(l) 

AUTHOR 

Copyright © 1989,1991 byjef Poskanzer. 

12 January 1991 


pnmenlarge 

pnmeniarge — Read a portable anymap and enlarge it N times 

SYNOPSIS 

pnmenlarge N [pnmf i I e ] 

DESCRIPTION 

pnmenlarge reads a portable anymap as input, replicates its pixels n times, and produces a portable anymap as output. 

pnmenlarge can only enlarge by integer factors. The slower but more general pnmscaie can enlarge or reduce by arbitrary 
factors, and pbmreduce can reduce by integer factors, but only for bitmaps. 

If you enlarge by a factor of 3 or more, you should probably add a pnmsmooth step; otherwise, you can see the original pixels 
in the resulting image. 

SEE ALSO 

pbmreduce(l), pnmscale(l), pnmsmooth(l), pnm(5) 

AUTHOR 

Copyright© 1989 byjef Poskanzer. 

26 February 1989 


pnmfile 

pnmf iie— D escri be a portabl e anymap 

SYNOPSIS 

pnmf ile [pnmf i I e ] ... 

DESCRIPTION 

pnmf iie reads one or more portable anymaps as input and writes out short descriptions of the image type size, and so on. 
This is mostly for use in shell scripts, sotheformatisnot particularly pretty. 

SEE ALSO 

pnm(5), file(l) 



pnmgamma 


387 


AUTHOR 

Copyright© 1991 byjef Poskanzer. 


9 January 1991 


pnmflip 

pnmfiip — Perform one or more flip operations on a portable anymap 

SYNOPSIS 

pnmflip [-left right|-lr][-topbottom!-tb][-transpose!-xy][-rotate90|-r90|-ccw ] 

[-rotate270]-r270|-cw ][-rotate180j-rl80][pnmf i I e] 

DESCRIPTION 

pnmflip reads a portable anymap as input, performs one or more flip operations in the order specified, and writes out a 
portable anymap. 

OPTIONS 

The flip operations available are left for right (-left night or -ir); top for bottom (-topbottom or - tb); and transposition (- 
transpose or -xy). In addition, somecanned concatenationsareavailable -rotate90 or -ccw isequivalent to -transpose - 
topbottom; -rotate270 Or -cw is equivalent to -transpose -leftright; and -rotate180 is equivalent to -leftright -topbottom. 

All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

pnmrotate(l), pnm(5) 

AUTHOR 

Copyright© 1989 byjef Poskanzer. 

25 July 1989 


pnmgamma 

pnmgamma— Perform gamma correction on a portable anymap 

SYNOPSIS 

pnmgamma value [pnmf i I e ] 

pnmgamma redvalue greenvalue bluevalue [pnmfile] 

DESCRIPTION 

pnmgamma reads a portable anymap as i nput, performs gamma correction, and produces a portable anymap as output. 

The arguments specify what gammavalue(s) to use. A value of 1.0 leaves the image alone, less than 1 darkensit, and greater 
than 1 lightens it. 

SEE ALSO 

pnm(5) 

AUTHOR 

Copyright© 1991 by Bill Davidson andJef Poskanzer. 


12 January 1991 
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pnmhistmap 

pnmhistmap— Draw a histogram for a PGM orPPM file 

SYNOPSIS 

pnmhistmap [-black][-white][-max N ][-verbose] [pnmf i I e] 

DESCRIPTION 

pnmhistmap reads a portable anymap as input, although bitmap (PBM) input produces an error message and no image, and 
produces an image showing a histogram of the color (or gray) values in the input. A graymap (PGM ) input produces a 
bitmap output. A pixmap (PPM ) input produces pixmap output with three overlaid histograms: a red one for the red input, 
a green one for the green input, and a blue onefor the blue input. The output is fixed in size 256 pixels wide by 200 pixels 
high. 

OPTIONS 

-black Ignores the count of black pixelswhen scaling the histogram. 

-white Ignores the count of white pixels when scaling the histogram. 

The -black and -white options, which can be used separately or together, are useful for images with a large percentage of 
pixels whose value is zero or 255, which can cause the remaining histogram data to become unreadably small. N otethat, for 
pixmap inputs, these optionsapply to all colors; if, for example, the input has a large number of bright-red areas, you will 
probably want to use the -white option. 

-max n ForcethescalingofthehistogramtouseW as the largest-count value. T his is useful for i nputs with a large 
percentage of single-color pixels that are not black or white. 

-verbose Report the progress of maki ng the histogram, including the largest-count value used to scale the output. 

All flags can be abbreviated to their shortest unique prefix. 

BUGS 

Assumes maxvai is always 255.1 mages with a smaller maxvai will only use the lower-value side of the histogram. This can be 
overcome either by piping the input through pnmdepth 255 or by cutting and scaling the lower-value side of the histogram. 

N either is a particularly elegant solution. 

Should allow the output size to be specified. 

SEE ALSO 

pgmhist(l), ppmhist(l), pgm(5), ppm(5) 

AUTHOR 

Wilson H . Bent, Jr. (whb@usc.edu). 

25 October 1993 


pnmindex 

pnmindex— Build a visual index of a bunch of anymaps 

SYNOPSIS 

pnmindex [-size N][ -across N][ -colors N ][- black] pnmfile ... 

DESCRIPTION 

This script makes small versions of a bunch of anymaps, adds labels, and concatenates them together into a collage. 
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OPTIONS 

-size Controlshow big each imagebecomes; the default is 100 x 100 . 

-across Controls how many images are in each row; the default is six. 

-colors Controlshow many colors the final index gets quantized to, if quantization is necessary; the default is256. 

-black C ontrols the color of the padding between the images; normally it's white and the labels are black lettering on 
white background, but the -black flag reverses this. 

SEE ALSO 

pnmscale(l), pnmcat(l), pbmtext(l), ppmquant(l), pnm(5) 

BUGS 

It's very slow. 

It's a csh script, csh scripts are not portable to System V. Scripts in general are not portable to non-U NIX environments. 

AUTHOR 

Copyright© 1991 byjef Poskanzer. 

9 January 1991 

pnminvert 

pnminvert — I nvert a portable anymap 

SYNOPSIS 

pnminvert [pnmf i I e ] 

DESCRIPTION 

pnminvert reads a portable anymap as input, inverts it black for white, and produces a portable anymap as output. 

SEE ALSO 

pnm(5) 

AUTHOR 

Copyright© 1989 byjef Poskanzer. 

8 August 1989 

pnmmargin 

pnmmargin— Add a border to a portable anymap 

SYNOPSIS 

pnmmargin [-white! - black J -color col orspec ] size [pnmfile] 

DESCRIPTION 

pnmmargin reads a portable anymap as input, adds a border of the specified number of pixels, and produces a portable anymap 
as output. 
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OPTIONS 

You can specify the border color with the -white, -black, and -color flags. If no color is specified, the program makes a 
guess. 

SEE ALSO 

pnm(5) 

BUGS 

It's a script. Scripts are not portable to non-U N IX environments 

AUTHOR 

Copyright© 1991 byjef Poskanzer. 

9 January 1991 


pnmnlfilt 

pnmnifiit —N onlinear filters: smooth, alphatrim mean, optimal estimation smoothing, edge enhancement. 

SYNOPSIS 

pnmnlfilt alpha radius [pnmfile] 

DESCRIPTION 

This is something of a Swiss army knife filter. It has three distinct operating modes. In all of the modes, each pixel in the 
image is examined and processed according to it and its surrounding pixels values. Rather than using the nine pixels in a 3 x 3 
block, seven hexagonal area samples are taken, the size of the hexagons being controlled by the radius parameter. A radius 
value of 0.3333 m eans that the sa/en hexagons exactly fit into the center pixel (that is, there will be no filtering effect). A 
radius value of i .0 means that the sa/en hexagons exactly fit a 3 x 3 pixel array. 

ALPHA-TRIMMED MEAN FILTER (0.0 < = alpha < = 0.5) 

The value of the center pixel will be replaced by the mean of the sa/en hexagon values, but the seven values are sorted by size 
and the top and bottom alpha portion of the sa/en are excluded from the mean. This implies that an alpha value of 0.0 gives 
the same sort of output asanormal convolution (that is, averaging or smoothing fi Iter), where radius will determinethe 
"strength" of thefilter. A good valueto start from for subtle filtering isaipha = 0.0, radius = 0.55. For a more blatant effect, 
try alpha = 0.0 and radius = 1 . 0 . 

An alpha value of 0.5 will cause the median value of the seven hexagons to be used to replace the center pixel value. This sort 
of filter is good for eliminating "pop” or single pixel noise from an image without spreading the noise out or smudging 
features on the image. Judicious use of the radius parameter will fine-tune the filtering. Intermediate values of alpha give 
effects somewhere between smoothing and "pop” noise reduction. For subtle filtering, try starting with values of alpha = 0.4, 
radius = 0.6. For a more blatant effect, try alpha = 0.5, radius = 1.0. 

OPTIMAL ESTIMATION SMOOTHING, (1.0 < = alpha < = 2.0) 

T his type of filter applies a smoothing filter adaptively over the image. For each pixel, the variance of the surrounding 
hexagon values is calculated, and the amount of smoothing is made inversely proportional to it. The idea is that if the 
variance is small, then it is due to noise in the image, while if the variance is large, it is because of "wanted" image features. 

As usual, the radius parameter controls the effective radius, but it probably advisable to leave the radius between 0.8 and 1.0 
for the variance calculation to be meaningful. The alpha parameter sets the noise threshold, over which less smoothing will 
be done. This means that small values of alpha will give the most subtle filtering effect, while large values will tend to smooth 
all parts of the image. You could start with values like alpha = 1.2, radius = 1 .0 and try increasing or decreasing the alpha 
parameter to get the desired effect. This type of filter is best for filtering out dithering noise in both bitmap and color images. 
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EDGE ENHANCEMENT. (-0.1 > = alpha > = -0.9) 

This is the opposite type of filter to the smoothing filter. It enhances edges. The alpha parameter controls the amount of 
edge enhancement, from subtle (- 0 . 1 ) to blatant (- 0 . 9 ). The radius parameter controls the effective radius as usual, but 
useful values are between 0.5 and 0 . 9 . Try starting with values of alpha = 0 . 3 , radius = 0 . 8 . 

COMBINATION USE 

The various modes of pnmnifiit can be used one after the other to get the desired result. For instance to turn a monochrome 
dithered image into a grayscale image, you could try one or two passes of the smoothing filter, followed by a pass of the 
optimal estimation filter, then some subtle edge enhancement. N otethat using edge enhancement is only likely to be useful 
after one of the nonlinear filters (alpha-trimmed mean or optimal estimation filter), as edge enhancement is the direct 
opposite of smoothing. 

For reducing color quantization noise in images (that is, turning GIF files back into 24-bit files), you could try a pass of the 
optimal estimation filter (alpha 1 . 2 , radius 1 . 0 ), apass of the median filter (alpha 0 . 5 , radius 0 . 55 ), and possibly a pass of 
the edge enhancement filter. Several passes of the optimal estimation filter with declining alpha values are more effective than 
a single pass with a large alpha value. As usual, there is a tradeoff between filtering effectiveness and loosing detail. Experi¬ 
mentation is encouraged. 

REFERENCES 

The alpha-trimmed mean filter is based on the description in/EEECG&A,May 1990, page 23, by M ark E. Lee and Richard 
A. Redner, and has been enhanced to allow continuous alpha adjustment. 

The optimal estimation filter is taken from an article "Converting D ithered Images Back to Grayscale” by Allen Stenger, Dr. 
Dobb'sjournal, N ovember 1992, and thisarticle references "D igital Image Enhancement and N oise Filtering by U se of Local 
Statistics” byJong-Sen Lee, IEEE Transaction son Pattern Analysis and M achine Intelligence, M arch 1980. 

Theedge enhancement details are from pgmenhance(l), which is taken from Philip R. Thornpson'sxim program, which in 
turn took it from Section 6 of "D igital H alftonesby Dot D iffusion" by D. E. Knuth, ACM Transaction on Graph icsVol. 6, 

N 0 .4, October 1987, which in turn got it from two 1976 papers by J. F. Jarvis et al. 

SEE ALSO 

pgmenhance(l), pnmconvol(l), pnm(5) 

BUGS 

Integers and tables may overflow if ppmjviaxmaxval is greater than 255 . 

AUTHOR 

GraemeW. Gill (graene@labtam.oz.au). 

5 February 1993 


pnmnoraw 

pnmnoraw— Force a portable anymap into plain format 

SYNOPSIS 

pnmnoraw [pnmf i I e ] 

DESCRIPTION 

pnmnoraw reads a portable anymap as input and writes it out in plain (nonraw) format. T his is fairly useless if you haven't 
defined the pbmplus_rawbits compile-time option. 



Parti: User Commands 



SEE ALSO 

pnm(5) 

AUTHOR 

Copyright© 1991 byjef Poskanzer. 


8 January 1991 


pnmpad 

pnmpad— Add borders to portable anymap 

SYNOPSIS 

pnmpad [-whitej-black] [-1#] [-r#] [-t#] [-b#] [pnmfile] 

DESCRIPTION 

pnmpad reads a portable anymap as input and outputs a portable anymap with extra borders of the sizes specified. The color of 
the borders can be set to black or white (default black). 

SEE ALSO 

pbmmake(l), pnmpaste(l), pbm(5) 

AUTHOR 

Copyright© 1990 by Angus Duggan. Copyright© 1989 byjef Poskanzer. 

pnmpaste 

pnmpaste — Paste a rectangle into a portable anymap 

SYNOPSIS 

pnmpaste [-replace!-or|-and j -xor] frompnmfile x y [i ntopnmfi I e ] 

DESCRIPTION 

pnmpaste reads two portable anymaps as input, inserts the first anymap into the second at the specified location, and produces 
a portable anymap the same size as the second as output. If the second anymap is not specified, it is read from stdin. Thex 
and y can be negative in which case they are i nterpreted relative to the right and bottom of the anymap, respectively. 

This tool is most useful in combination with pnmcut. For instance, if you want to edit a small segment of a large image, and 
your image editor cannot edit the large image, you can cut out the segment you are interested in, edit it, and then paste it 
back in. 

Another useful companion tool ispbmmask. 

Theoptional flag specifies the operation to use when doing the paste. T he default is -replace. Theother logical operations 
are only allowed if both input images are bitmaps. These operations act as if white is true and black is false. 

All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

pnmcut(l), pnminvert(l), pnmarith(l), pnm(5), pbmmask(l) 



pnmseale 



AUTHOR 

Copyright © 1989,1991 byjef Poskanzer. 


21 February 1991 


pnmrotate 

pnmrotate — Rotate a portable anymap by some angle 

SYNOPSIS 

pnmrotate [-noantialias] angle [pnmfile] 

DESCRIPTION 

pnmrotate reads a portable anymap as input, rotates it by the specified angle, and produces a portable anymap as output. If 
the input file is in color, the output will be, too; otherwise, it will be grayscale. The angle is in degrees (floating-point), 
measured counter-clockwise. It can be negative, but it should be between -90 and 90. Also, for rotations greater than 45 
degrees you may get better results if you first usepnmfiip to do a 90-degree rotation and then pnmrotate less than 45 degrees 
back the other direction. 

The rotation algorithm is Alan Paeth's three-shear method. Each shear is implemented by looping over the source pixels and 
distributing fractions to each of the destination pixels. This has an antialiasing effect— it avoids jagged edges and similar 
artifacts. H owever, it also means that the original colorsorgray levels in the image are modified. If you need to keep 
precisely the same set of colors, you can use the -noantiaiias flag. This does the shearing by moving pixels without changing 
their values. If you want antialiasing and don't care about the precise colors, but still need a limited ‘number* of colors, you 
can run the result through ppmquant. 

All flags can be abbreviated to their shortest unique prefix. 

REFERENCES 

"A Fast Algorithm for General Raster Rotation” by Alan Paeth, Graphics Interface '86, pages 77-81. 

SEE ALSO 

pnmshear(l), pnmflip(l), pnm(5), ppmquant(l) 

AUTHOR 

Copyright © 1989,1991 byjef Poskanzer. 

12 January 1991 


pnmscale 

pnmscaie — Scale a portable anymap 

SYNOPSIS 

pnmscale s [pnmf i I e ] 

pnmscale -xsize]-width]-ysizej -heights [pnmfile] 
pnmscale -xscale]-yscale s [pnmfile] 

pnmscale -xscale]-xsizej-width s -yscale]-ysize]-height s [pnmfile] 
pnmscale -xysize x y [pnmfile] 
pnmscale -pixels n [pnmfile] 
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DESCRIPTION 

pnmscaie reads a portable anymap as i nput, scales it by the specified factor or factors, and produces a portable anymap as 
output. If the input file is in color, the output will be too; otherwise, it will be grayscale. You can both enlarge (scale factor > 
1) and reduce (scale factor < 1). 

You can specify one dimension as a pixel size, and the other dimension will be scaled correspondingly. 

You can specify one dimension as a scale, and the other dimension will not be scaled. 

You can specify different sizes or scales for each axis. 

You can use the special -xysize flag, which fits the image into the specified size without changing the aspect ratio. 

Or, you can use the -pixels flag, which fits the i mage into the specified number of pixels without changing the aspect ratio. 
All flags can be abbreviated to their shortest unique prefix. 

If you enlarge by a factor of three or more you should probably add apnmsmooth step; otherwise, you can see the original 
pixels in the resulting image. 

SEE ALSO 

pbmreduce(l), pnmenlarge(l), pnmsmooth(l), pnm(5) 

AUTHOR 

Copyright © 1989,1991 byjef Poskanzer. 

12 January 1991 


pnmshear 

pnmsheai — Shear a portable anymap by some angle 

SYNOPSIS 

pnmshear [-noantialias] angle [pnmfile] 

DESCRIPTION 

pnmshear reads a portable anymap as i nput, shears it by the specified angle, and produces a portable anymap as output. If the 
input fileisin color, theoutput will be too; otherwise, it will be grayscale. Theangleisin degrees (floating-point), and 
measures this: 

+ - + + - + 

li!\\ 

| OLD]]\NEW \ 

I I!an\\ 

+-+ |gle+-+ 

If the angle is negative it shears the other way: 

+-+ j-an+-+ 

lligi// 

| OLD I I el NEW / 

I!!// 

+ - + + - + 

The angle should not get too close to 90 or-90, or the resulting anymap will be unreasonably wide. 

T he shearing isimplemented by looping over the source pixels and distributing fractions to each of the destination pixels. 
This has an antialiasing effect— it avoids jagged edges and similar artifacts. H owever, it also means that the original colors or 
gray levels in the image are modified. If you need to keep precisely the same set of colors, you can usethe-noantiaiias flag. 
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This does the shearing by moving pixels without changing their values. If you want antialiasing and don't care about the 
precise colors but still need a limited -number* of colors, you can run the result through ppmquant. 

All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

pnmrotate(l), pnmflip(l), pnm(5), ppmquant(l) 

AUTHOR 

Copyright © 1989,1991 byjef Poskanzer. 

12 January 1991 


pnmsmooth 

pnmsmooth— Smooth out an image 

SYNOPSIS 

pnmsmooth [pnmf i I e ] 

DESCRIPTION 

pnmsmooth smooths out an image by replacing each pixel with the average of its nine immediate neighbors. It is implemented 
as a simple script using pnmconvoi. 

SEE ALSO 

pnmconvol(l), pnm(5) 

BUGS 

It's a script. Scripts are not portable to non-U N IX environments 

AUTHOR 

Copyright© 1989,1991 byjef Poskanzer 

13 January 1991 


pnmtile 

pnmtiie— Replicate a portable anymap into a specified size 

SYNOPSIS 

pnmtile width height [pnmfile] 

DESCRIPTION 

pnmtile reads a portable anymap as input, replicates it until it is the specified size, and produces a portable anymap as output. 

SEE ALSO 

pnm(5) 

AUTHOR 

Copyright© 1989 byjef Poskanzer. 


13 May 1989 
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pnmtoddif 

pnmtoddif — C onvert a portable anymap to D DIF format 

SYNTAX 

pnmtoddif pnmtoddif [-resolution x y] [pnmfile [ddiffile]] 

OPTIONS 

resolution x y T he horizontal and vertical resolution of the output image in dots per inch. D efaults to 78dpi. 
pnmf i i e T he filename for the image file in PN M format. If this argument is omitted, input is read from stdin. 

ddiffile The filename for the image file to be created in DD IF format. If this argument is omitted, theddi f f i i e is 

written to standard output. It can only specified if a pnmf i i e is also specified. 

DESCRIPTION 

pnmtoddif takes a portable anymap from standard input and converts it into a DD IF image file on standard output or the 
specified DDIF file. 

PBM format (bitmap) data is written as 1-bit D DIF, PGM format data (grayscale) as 8-bit grayscale D DIF, and PPM format 
data is written as 8,8,8-bit color D D IF. All D D IF image files are written as uncompressed. The data plane organization is 
interleaved by pixel. 

In addition to the number of pixels in the width and height dimension, DD IF images also carry information about the size 
that the image should have, that is the physical space that a pixel occupies. PBM PLUS images do not carry this information, 
hence it has to be externally supplied. The default of 78 dpi has the beneficial property of not causing a resize on most D igital 
Equipment Corporation color monitors 

AUTHOR 

Burkhard N eidecker-Lutz 

Digital Equipment Corporation, CEC Karlsruhe 

neideck@nestvx.enet.dec.com 

pnmtofits 

pnmtofits— Convert a portable anymap into FITS format 

SYNOPSIS 

pnmtofits [-max f ] [-min f ] [pnmf i I e ] 

DESCRIPTION 

pnmtofits reads a portable anymap as input and produces a FITS (Flexible I mage T ransport System) file as output. The 
resolution of the output file is either 8 bits/pixel, or 16 bits/pixel, depending on the value of maxvai in the input file. If the 
input file is a portable bitmap or a portable graymap, the output file consists of a single plane image (naxis = 2). If instead 
theinput file isa portable pi xmap, the output file will consist of a three-plane image (naxis = 3, naxis 3 = 3). A full 
description oftheFITSformatcan be found in AstronomySi Astrophysics Supplement Series44 (1981), page 363. 

OPTIONS 

Flags -min and -max can be used to set datamax, datamin, bscale, and bzero in the FITS header, but do not cause the data to 
be rescaled. 

SEE ALSO 

fitstopnm(l), pgm( 5 ) 
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AUTHOR 

Copyright © 1989 by W ilson H. Bent (whb@hoh- 2 .att.com), with modifications by Alberto Accomazzi 
(alberto@cfa.harvard.edu). 

5 December 1992 


pnmtops 

pnmtops— C onvert portable anymap to PostScript 

SYNOPSIS 

pnmtops [-scale s][-turn|-noturn][-rlej-runlength][-dpi n][-width n][- height n] 

[ - center! - nocenter] [pnmf i I e ] 

DESCRIPTION 

pnmtops reads a portable anymap as input and produces encapsulated PostScript as output. 

If the input file is in color (PPM), a color PostScript file gets written. Some PostScript interpreters can't handle color 
PostScript. If you have one of these, you will need to run your image through ppmtopgm first. 

Notethatthereisno pstopnm tool; thistransformation isone-way, because a pstopnm tool would be a full-fledged PostScript 
interpreter, which is beyond the scope of this package. H owever, seethepsidtopgm tool, which can read grayscale non-run- 
length PostScript image data. Also, if you're willing to install the fairly large GhostScript package, it comes with apstdppm 
script. 

OPTIONS 

The - scale flag controls the scale of the result. The default scale is i, which on a 300dpi printer such as the Apple 
LaserWriter makes the output look about the same size as the input would if it was displayed on atypical 72dpi screen. T o 
getonePNM pixel per 300dpi printer pixel, use -scale 0 . 25 . 

The - turn and -noturn flags control whether the image gets turned 90 degrees. N ormally, if an image is wider than it is tall, 
it gets turned automatically to better fit the page. If the - turn flag is specified, it will be turned no matter what its shape; and 
if the -noturn flag isspecified, itwill not be turned no matter what its shape. 

The -rie or - runlength flag specifies run-length compression. This may savetime if the host-to-printer link is slow; but 
normally theprinter'sprocessingtimedominates, so -rie makes things slower. 

The -dpi flag lets you specify the dots per inch of your output device. The default is 300 dpi. In theory PostScript is device¬ 
independent and you don't have to worry about this, but in practice its raster rendering can have unsightly bands if the 
device pixels and theimage pixels aren't in sync. 

The -width and -height flags let you specify the size of the page. The default is 8.5 inches by 11 inches. 

With the -nocenter flag, the output is not centered on the page; it appears in the upper-left corner. This is useful for 
programs that can include PostScript files, but can't cope with pictures that are not positioned in the upper-left corner. The 
default is -center--the image is centered on the page. 

All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

pnm(5), psidtopgm(l) 

AUTHOR 

Copyright© 1989,1991 byJefPoskanzer. M odified N ovember 1993 byWolfgangStuerzIinger (wrzi@gup.um-iinz.ac.atj. 

26 October 1991 
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pnmtorast 

pnmtorast— C onvert a portable pixmap into a Sun raster file 

SYNOPSIS 

pnmtorast [ -standard! -rle] [pnmf i I e ] 

DESCRIPTION 

pnmtorast reads a portable pixmap as input and produces a Sun raster file as output. 

Color valuesin Sun raster files are eight bits wide, so pnmtorast will automatically scale colors to haveamaxvai of 255. An 
extra pnmdepth step is not necessary. 

OPTIONS 

The -standard flag forces the result to be in rt_standard form; the -rie flag, rt^byte_encoded, which is smaller but, well, less 
standard. T he default is -ne. 

All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

rasttopnm(l), pnm( 5 ) 

AUTHOR 

Copyright © 1989,1991 byjef Poskanzer. 

12 January 1991 


pnmtosgi 

pnmtosgi— Convert a portable anymap to an SGI image file 

SYNOPSIS 

pnmtosgi [-verbatim]-rle][-imagename Name ][pnmfile] 

DESCRIPTION 

pnmtosgi reads a portable anymap as input and produces an SGI imagefile as output. The SGI imagewill be two-dimen¬ 
sional (onechannel) for PBM and PGM input, and three-dimensional (threechannels) for PPM . 

OPTIONS 

-verbatim W rite an uncompressed file. 

-rie (default) Write a compressed (run-length-encoded) file. 

-imagename name W rite the string name into the imagename field of the header. T he n a me string is limited to 79 characters. If 
no name is given, pnmtosgi writes no name into thisfield. 

BUGS 

Probably. 

REFERENCES 

SGI image file format documentation (draft vO. 95) by Paul Haeberli (paui@sgi.com). Available via FTP at sgi.comigraphics/ 

SGIIMAGESPEC. 
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SEE ALSO 

pnm(5), sgitopnm(l) 

AUTHOR 

Copyright © 1994 by I ngo 1/1/ ilken (Tngo.Wilken@informatik. uni-Oldenburg. dej. 

29 January 1994 


pnmtosir 

pnmtosii — C onvert a portable anymap into a Solitaire format 

SYNOPSIS 

pnmtosir [pnmfile] 

DESCRIPTION 

pnmtosir reads a portable anymap as input and produces a Solitaire image recorder format. 

pnmtosir produces an MGI TYPE 17 fi le for P B M and PGM files. For ppm, itwritesan MGI TYPE 11 file. 

SEE ALSO 

sirtopnm(l), pnm(5) 

AUTHOR 

Copyright © 1991 by M arvin Landis. 

20 March 1991 


pnmtotiff 

pnmtotiff— Convert a portable anymap into aTIFF file 

SYNOPSIS 

pnmtotiff [-nonej-packbitsj -lzwj-g3j-g4][-2d][-fill][-predictor n] 

[-msb21sb|-lsb2msb] [-rowsperstrip n] [pnmfile] 

DESCRIPTION 

pnmtotiff reads a portable anymap asinput. ProducesaTIFF fileas output. 

OPTIONS 

By default, pnmtotiff creates aTIFF file with LZW compression. This is your best bet most of the time. FI owever, some 
TIFF readers can't deal with it. If you want to try another compression scheme or tweak some of the other even more 
obscure output options, there are a number of flags to play with. 

The-none, -packpits, -lzw, -g3,and-g4 options are used to override the default and set the compression schemeusedin 
creati ng the output file. The CC ITT Group 3 and Group 4 compression algorithms can only be used with bilevel data. The 
- 2 d and -fin optionsare meaningful only with Group 3 compression: - 2 d requests two-dimensional encoding, while -fin 
requests that each encoded scanline be zero-filled to a byte boundary. The - predictor option is only meaningful with LZW 
compression: a predictor value of 2 causes each scanline of the output image to undergo horizontal differencing before it is 
encoded; a value of 1 forces each scan line to be encoded without differencing. By default, pnmtotiff creates aTIFF file with 
msb-to-isb fill order. The -msb 2 isb and -isb 2 msb optionsare used to override the default and set the fill order used in 
creating the file. The - rowsperstrip option can be used to set the number of rows (scan lines) in each strip of data in the 
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output file. By default, the output file has the number of rows per strip set to a value that will ensure each strip is no more 
than eight kilobytes long. 

BUGS 

This program is not self-contained. To use it you must fetch the TIF F Software package listed in the other, systems file and 
configure pbmplus to useiibtiff. SeePBM -PLUS'S M akefile for details on this configuration. 

SEE ALSO 

tifftopnm(l), pnm(5) 

AUTHOR 

Derived byjef Poskanzerfrom ras 2 tiff.c, which is Copyright® 1990 bySun M icrosystems, Inc. Author: Patrick J. 

N aughton (naughton@wind .sun. com). 

13 January 1991 


pnmtoxwd 

pnmtoxwd— Convert a portableanymap into an X11 window dump 

SYNOPSIS 

pnmtoxwd [-pseudodepth n][-directcolor][pnmf i I e] 

DESCRIPTION 

pnmtoxwd reads a portable anymap as i nput and produces an Xll window dump as output. This window dump can be 
displayed using the xwud tool. 

Normally, pnmtoxwd produces a StaticG ray dump file forPBM and PGM files. For ppm, it writes a Pseudocolor dump file if 
there are up to 256 colors in the input, and a D irectC olor dump fi le otherwise. T he -directcolor flag can be used to force a 
D irectColor dump. The - pseudodepth flag can be used to change the depth of Pseudocolor dumps from the default of 8 bits/ 
256 colors. 

SEE ALSO 

xwdtopnm(l), pnm(5), xwud(l) 

AUTHOR 

Copyright® 1989,1991 byjef Poskanzer. 

24 September 1991 


ppm3d 

ppm3d— Convert two portable pi xmap into a red/blue 3D glasses pixmap 

SYNOPSIS 

ppm3d I ef t ppmf i I e rightppmfile [horizontaloffset] 

DESCRIPTION 

ppm3d reads two portable pixmaps as input and produces a portable pixmap as output, with the images overlapping by 
horizontai_otf set pixels in blurred format. 

horizontai_otf set defaults to 30 pixels. Pixmapsmust bethesame size. 
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SEE ALSO 

ppm(5) 

AUTHOR 

Copyright © 1993 by D avid K. D rum. 


2 N ovember 1993 


ppmbrighten 

ppmbrighten— Change an image's saturation and value from an H SV map 

SYNOPSIS 

ppmbrighten [-n] [-s <+- saturation^ [-v <+- value>] <ppmfile> 

DESCRIPTION 

ppmbrighten reads a portable pixmap as input, converts the image from RGB space to H SV space, and changes the value by 

<+- vaiue> as a percentage; thesamewith the saturation. Use 

ppmbrighten -v 100 

to add 100 percent to the value. 

Then option normalizes the value to exist between 0 and 1 (normalized). 

SEE ALSO 

pgmnorm(l), ppm(5) 

AUTHOR 

Copyright® 1990 by Brian M offet. Copyright® 1989 byjef Poskanzer. 

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is 
hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this 
permission notice appear in supporting documentation. This software isprovided "asis" without express or implied 
warranty. 

NOTES 

This program does not change the number of colors. 

20 N ovember 1990 


ppmchange 

ppmchange— Change all pixels of one color to another in a portable pixmap 

SYNOPSIS 

ppmchange ol dcol or newcolor [...] [ppmfile] 

DESCRIPTION 

ppmchange reads a portable pixmap as input and changes all pixels of oi dcol or to n ewe oi or , leaving all others unchanged. Up 
to 256 colors may be replaced by specifying couples of colors on the command line. 
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Thecolorscan be specified in five ways: 

■ A name, assuming that a pointer to an X 11-style color namesfilewascompiled in. 

■ An X 11-style hexadecimal specifier: ngb: r/g/b, where r, g, and b are each 1- to 4-digit hexadecimal numbers. 

■ An X 11-style decimal specifier: rgbi: r/g/b, where r, g, and b are floating-point numbers between 0 and 1. 

■ For backwards compatibility, an Old-X 11-Style hexadecimal number: #rgb, #rrggbb, ffrrrgggbbb, Or#rrrrggggbbbb. 

■ For backwards compatibility, a triplet of numbers separated by commas: r,g,b, where r, g, and b are floating-point 
numbers between 0 and 1. (This style was added beforeM IT cameupwith the similar rgbi style) 

SEE ALSO 

pgmtoppm(l), ppm(5) 

AUTHOR 

Wilson H . Bent, Jr. (whb@usc.edu), with modifications by Alberto Accomazzi (alberto@cfa.harvard.edu). 

3 December 1993 


ppmdim 

ppmdim — Dima portable pi xmap down to total blackness 

SYNOPSIS 

ppmdim di mf act or [ppmf i I e ] 

DESCRIPTION 

ppmdim reads a portable pixmap as input and diminishes its brightness by the specified dimf actor down to total blackness. T he 
di mfactor may be in the range from 0.0 (total blackness, deep night, nada, null, nothing) to 1.0 (original picture's bright¬ 
ness). 

As pnmgamma does not do the brightness correction in the way I wanted it, I wrote this small program, 
ppmdim is similar to ppmbrighten, but not exactly the same. 

SEE ALSO 

ppm(5), ppmflash(l), pnmgamma(l), ppmbrighten(l) 

AUTHOR 

Copyright© 1993 by Frank N eumann. 

16 N ovember 1993 


ppmdist 

ppmdist — Simplistic grayscale assignment for machine-generated color images 

SYNOPSIS 

ppmdist [-intensity!-frequency][ppmf i I e] 

DESCRIPTION 

ppmdist reads a portable pixmap as input and performs a simplistic grayscale assignment intended for use with grayscale or 
bitmap printers. 



ppmdither 

Often conversion from ppm to pgm will yield an image with contrast too low for good printer output. The program maximizes 
contrast between the gray levels' output. 

A ppm input of n colors is read, and a pgm of n gray levels is written. The gray levels take on the values 0 .. .n-i, while maxvai 
takes on n-i. 

The mapping from color to stepped grayscalecan be performed in order of input pixel intensity, or input pixel frequency 
(number of repetitions). 

OPTIONS 

-frequency Sort input colors by the number of times a color appears in the input, before mapping to a/enly distrib¬ 
uted gray levels of output. 

-intensity Sort input colors by thei r grayscale intensity, before mapping to a/enly distributed gray levels of output. 
This is the default. 

BUGS 

H elpful only for images with a very small number of colors. Perhaps should have been an option to ppmtopgm(l). 

SEE ALSO 

ppmtopgm(l), ppmhist(l), ppm(5) 

AUTHOR 

Copyright© 1993 by Dan Stromberg. 

22 July 1992 

ppmdither 

ppmdither— 0 rdered dither for color images 

SYNOPSIS 

ppmdither [-dim di mensi on][-red shades][-green shades][-blue shades][ppmf i I e] 

DESCRIPTION 

ppmdither reads a portable pixmap as input, and applies dithering to it to reduce the number of colors used down to the 
specified number of shades for each primary. The default number of shades is red=5, green=9, biue=5, for a total of 225 
colors. To convert the image to a binary RGB format suitablefor color printers, use -red 2 -green 2 -blue 2 .Themaximum 
number of col ors that can be used is 256 and can be computed as the product of the number of red, green, and blue shades. 

OPTIONS 

-dim di mens i on T he size of the dithering matrix. M ust be a power of 2. 

-red shades The number of red shades to be used; minimum of 2. 

-green shades T he number of green shades to be used; minimum of 2. 

-blue shades T he number of blue shades to beused; minimum of 2. 

SEE ALSO 

pnmdepth(l), ppmquant(l), ppm(5) 

AUTHOR 

C opyright© 1991 by C hristos Zoulas. 



14 July 1991 



Parti: User Commands 



ppmflash 

ppmf lash— Brighten a picture up to complete white-out 

SYNOPSIS 

ppmf lash fl ashfactor [ppmfile] 

DESCRIPTION 

ppmf lash reads a portable pixmap as input and increases its brightness by the specified f i ashfactor up to a total white-out 
image. Then ashfactor may be in the range from 0.0 (original picture's brightness) to 1.0 (full white-out, The Second 
After). 

As pnmgamma does not do the brightness correction in the way I wanted it, I wrote this small program. 

This program is similar to ppmbrighten, but not exactly the same. 

SEE ALSO 

ppm(5), ppmdim(l), pnmgamma(l), ppmbrighten(l) 

AUTHOR 

Copyright© 1993 by Frank N eumann. 

16 N ovember 1993 


ppmforge 

ppmforge— Fractal forgeries of clouds, planets, and starry skies 

SYNOPSIS 

ppmforge [-clouds][-night][-dimension di men][-hour hour][-inclination|-tilt angle] 

[-mesh s i ze][-power factor ][-glaciers level ][-ice level ][-saturation sat] 

[-seed seed ] [-stars f r act i on][-xsizej-width wi dt h][-ysize|-height hei ght ] 

DESCRIPTION 

ppmforge generates three kindsof "random fractal forgeries,'' theterm coined by Richard F. VossofthelBM Thomas 
J. W atson Research Center for seemingly realistic pictures of natural objects generated by simple algorithms embodying 
randomness and fractal self-similarity. T he techniques used by ppmforge are essentially those given by Voss, particularly the 
technique of spectral synthesis explained in more detail by DietmarSaupe. (The"SeeAlso" subsection provides more 
detailed information about these men's work.) 

The program generates two varieties of pictures, planets and clouds, which are just different renderings of data generated in 
an identical manner, illustrating the unity of the fractal structureof these very different objects. A third type of picture, a 
starry sky, is synthesized directly from pseudorandom numbers. 

The generation of planets or clouds begins with the preparation of an array of random data in the frequency domain. The 
size of this array, the mesh size, can beset with the -mesh option; the larger the mesh, the more realistic the pictures, but the 
calculation time and memory requirement increases as the square of the mesh size. The fractal dimension, which you can 
specify with the -dimension option, determines the roughness of the terrain on the planet orthescaleof detail in theclouds. 
As the fractal dimension is increased, more high frequency components are added into the random mesh. 

After the mesh is generated, an inverse two-dimensional Fourier transform is performed upon it. This converts the original 
random frequency domain data into spatial amplitudes. You scale the real components that result from the Fourier transform 
into numbers from 0 to 1 associated with each point on themesh. You can further modify this number by applying a power 
law sca/eto it with the - power option. Unity scale I eaves the numbers unmodified; a power scale of 0.5 takes the square root 
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of the numbers in the mesh, while a power scale of 3 replaces the numbers in the mesh with their cubes. Power law scaling is 
best envisioned by thinking of the data as representi ng the ela/ation of terrain; powers I ess than oneyield landscapes with 
vertical scarps that look like glacial-carved valleys; powers greater than one make fairy-castle spires (which require large mesh 
sizes and high resolution for best results). 

After these calculations, you have an array of the specified size containing numbers that range from 0 to 1. Thepixmapsare 
generated as follows: 

clouds A color map iscreated that ranges from pure blue to white by increasing admixture (desaturation) of blue with 
white N umbers less than 0.5 are colored blue, and numbers between 0.5 and 1.0 are colored with corresponding 
levels of white, with 1.0 being pure white. 

Planet Themesh is projected onto a sphere. Values less than 0.5 are treated as water and values between 0.5 and 1.0 as 
land. The water areas are colored based on the water depth; land, based on its elevation. The random depth data 
are used to create clouds over the oceans. An atmosphere approximately I ike the Earth'sis simulated; its light 
absorption is calculated to create a blue cast around the limb of the planet. A function that rises from 0 to 1 based 
on latitude is modulated by the local elevation to generate polar icecaps— high altitude terrain carries glaciers 
farther from the pole. Based on the position of the star with respect to the observer, the apparent color of each 
pixel of the planet is calculated by ray-tracingfrom the star to the planet to the observer and applying a lighting 
model that sums ambient light and diffuse reflection (for most planets ambient light is zero, as their primary star 
is the only source of illumination). Additional random data are used to generate stars around the planet. 

Night A sequence of pseudorandom numbers is used to generate stars with a user-specified density. 

Cloud pictures always con tain 256 or fewer colors and may bedisplayed on most color-mapped devices without further 
processing. Planet pictures often contain tens of thousands of colors that must decompressed with ppmquant or ppmdither 
before encoding in a color-mapped format. If the display resolution is high enough, ppmdither generally produces better¬ 
looking planets, ppmquant tendsto create discrete color bands, particularly in theoceans, which are unrealistic and distract¬ 
ing. The number of colors in starry sky pictures generated with the - night option depends on the value specified for 
-saturation. Small values limit the color temperature distri bution of thestarsand reduce the number of colors in theimage. 
If the -saturation i s set to 0 , none of the stars will be colored and the resulting image will never contain more than 256 
colors. Night sky pictures with many different star colors often look best when color-compressed bypnmdepth rather than 
ppmquant or ppmdither. T ry newmaxvai settings of 63,3i, or 15 with pnmdepth to reduce the number of colors in the picture to 
256 or fewer. 

OPTIONS 

•clouds 

-dimension di men 


-glaciers I evel 


-hour hour 


Generate clouds. A pixmap of fractal clouds is generated. Selecting clouds setsthe default 
forfractal dimension to 2.15 and power scalefactorto 0 . 75 . 

Sets the fractal dimension to the specified dimen, which may beany floating-point value 
between 0 and 3. H igherfractal dimensionscreatemore"chaotic" images, which require 
higher resolution output and a larger FFT mesh size to look good. If no dimension is 
specified, 2.4 is used when generating planets and 2.15 for clouds. 

The floating-point 1 evel setting controls the extent to which terrain elevation causes ice to 
appear at lower latitudes. T he default value of 0 . 75 makes the polar caps extend toward the 
equator across high terrain and forms glaciers in the highest mountains, as on Earth. H igher 
values make ice sheets that cover more and more of the land surface, simulating planets in 
the midst of an ice age. Lower values tend to be boring, resulting in unrealistic geometrically 
precise ice cap boundaries. 

When generating a planet, hour is used as the hour angle at the central meridian. If you 
specify -hour 12 , for example, the planet will be fully illuminated, corresponding to high 
noon at the longitude at the center of the screen. You can specify any floating-point value 
between 0 and 24 for hour, but values which place most of the planet in darkness (0 to 4 
and 20 to 24) result in crescents which, while pretty, don't give you many illuminated pixels 
for the amount of computing that's required. If no -hour option is specified, a random hour 
angle is chosen, biased so that only 25 percent of the images generated will be crescents. 
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-ice I evel 

-inclination! 


-mesh size 


-night 

-power factor 


-saturation s 


Sets the extent of the polar ice caps to the given floating-point level. The default level of 
0.4 produces ice caps similar to those of the Earth. Smaller values reduce the amount of ice, 
while larger - ice settings create more prominent icecaps. Sufficiently large values, such as 
100 or more, in conjunction with small settings for -glaciers (try 0 . 1 ) create "ice balls" like 
Euro pa. 

-tilt angle T he inclination angle of the planet with regard to its primary star is set to angle, which can 
beany floating-point value from -90 to 90. The inclination angle can bethought of as 
specifying, in degrees, the "season" the planet is presently experiencing or, more precisely, 
the latitude at which the star transits thezenith at local noon. If 0, the planet isat equinox; 
the star is directly overhead at theequator. Positive values represent summer in the northern 
hemisphere; negative values summer in the southern hemisphere. The Earth's inclination 
angle, for example is about 23.5 at thejune solstice, 0 at the equinoxes in M arch and 
September, and -23.5 at the December solstice. If no inclination angle is specified, a 
random value between -21.6 and 21.6 degrees ischosen. 

Ameshofsize bysize will be used forthefast Fourier transform (FFT). N otethat 
memory requirements and computation speed increase as the square of si ze; if you double 
the mesh size, the program will use four times the memory and run four times as long. The 
default mesh is 256 x 256 , which produces reasonably good looking pictures while using half a 
megabyte for the 256 x 256 array of single precision complex numbers requi red by the FFT. 

On machines with limited memory capacity, you may have to reduce the mesh size to avoid 
running out of RAM . Increasing the mesh size produces better looking pictures; the 
difference becomes particularly noticeable when generating high-resolution images with 
relatively high fractal dimensions(between 2.2 and 3). 

A starry sky is generated. The stars are created by the same algorithm used for the stars that 
surround planet pictures, but the output consists exclusively of stars. 

Sets the power factor used to scale elevations synthesized from the FFT to f act or , which can 
beany floating-point number greater than zero. If no factor is specified, a default of 1.2 is 
used if a planet is being generated, or 0.75 if clouds are selected by the -clouds option. The 
result of the FFT image synthesis is an array of elevation values between 0 and 1. A 
nonunity power factor exponentiates each of these elevations to the specified power. For 
example, a power factor of 2 squares each value, while a power factor of 0.5 replaces each 
with its square root. (N otethat exponentiating values between 0 and 1 yields values that 
remain within that range.) Power factors less than 1 emphasizelarge-scaleelevation changes 
at the expense of small variations. Power factors greater than 1 increase the roughness of the 
terrain and, like high fractal dimensions, may require a larger FFT mesh size or higher 
screen resolution to look good. 

at Controls the degree of color saturation of the stars that surround planet pictures and fill 

starry skies created with the - night option. The default value of 125 creates stars that 
resemble the sky as seen by the human eye from Earth's surface. Stars aredim; onlythe 
brightest activate the cones in the human retina, causing color to be perceived. H igher 
values of sat approximate the appearance of stars from Earth orbit, where better dark 
adaptation, absence of sky glow, and the concentration of light from a given star onto a 
smal Ier area of the reti na than ks to the I ack of atmospheri c turbu Ience en hances the 
perception of color. Values greater than 250 create "sciencefiction" skies that, while pretty, 
don't occur in this universe. 

Thanks to the inverse square law combined with nature's love of mediocrity, there are 
many, many dim stars for every bright one. This population relationship is accurately 
reflected in the skies created by ppmforge. Dim, low mass starslivemuch longer than bright, 
massive stars; consequently there are many reddish stars for every blue giant. This relation¬ 
ship is preserved by ppmforge. You can reverse the proportion, simulating the sky as seen in a 
starburst galaxy, by specifying a negative sat value. 
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-seed num 


-stars f r acti on 


-xsize | -width width 


-ysize]-height height 


Sets the seed for the random number generator to the integer num. The seed used to create 
each picture is displayed on standard output (unless suppressed with the -quiet option). 
Pictures generated with the same seed will be identical. If no -seed is specified, arandom 
seed derived from the date and time will be chosen. Specifying an explicit seed allows you to 
re-render a picture you particularly like at a higher resolution or with different viewing 
parameters. 

Specifies the percentage of pixels, in tenths of a percent, that will appear as stars, either 
surrounding a planet or filling the entire frame if -night is specified. The default f racti on is 
100 . 

Sets the width of the generated image to wi dth pixels. The default width is 256 pixels. 

Images must beat least as wide as they are high; if a width less than the height is specified, it 
will beincreased to equal theheight. If you must havea long, skinny pixmap, makeasquare 
onewith ppmtorge, then usepnmcut to extract a portion of theshapeand size you require. 
Sets the height of the generated image to hei ght pixels. T he default height is 256 pixels. If 
the height specified exceeds the width, thewidth will beincreased to equal theheight. 


All flags can be abbreviated to their shortest unique prefix. 


BUGS 

The algorithms require the output pixmap to beat least as wide as it is high, and thewidth to bean even number of pixels. 
These constraints are enforced by increasing the size of the requested pixmap if necessary. 

You may have to reduce the F FT mesh size on machines with 16-bit integers and segmented pointer architectures. 


SEE ALSO 

pnmcut(l), pnmdepth(l), ppmdither(l), ppmquant(l), ppm(5) 

"Random Fractal Forgeries” by Richard F. Voss, in Fundamental Algorithms for Computer Graphics by Earnshaw et al. Berlin: 
Springer-V erlag, 1985. 

TheScienceOf Fractal Images edited by H. 0. Peitgen and D. Saupe. NewYork: Springer-V erlag, 1988. 


AUTHOR 

John Walker 
Autodesk SA 

Avenue desChamps-M ontantsl4b 
C FI -2074 M ARIN 

Sui ssel Sch wei zl Svi zzera/ Svizra/ Swi tzerl an d 
Usenet: kelvin0Autodesk.com 

Fax: 038/33 88 15 

Voice: 038/33 76 33 


Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is 
hereby granted, without any conditions or restrictions. This software is provided "as is” without express or implied warranty. 

PLUGWARE! If you likethis kind of stuff, you may also enjoyJamesGleick's "Chaos— TheSoftware” for M S-DOS, 
available for $59.95 from your local software store or directly from Autodesk, Inc., Attn: Science Series, 2320 M arinship 
Way, Sausalito, CA 94965, USA. Telephone: 800-688-2344 toll-free or, outside the U.S. 415-332-2344 Ext 4886. 

Fax: 415-289-4718. "Chaos—TheSoftware" includesamore comprehensive fractal forgery generator that creates three- 
dimensional landscapes as well ascloudsand planets, plus five more modules that explore other aspects of Chaos. The user 
guide of more than 200 pages includes an introduction byJamesGleick and detailed explanations by Rudy Rucker of the 
mathematics and algorithms used by each program. 


25 October 1991 
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ppmhist 

ppmhist — Print a histogram of a portable pixmap 

SYNOPSIS 

ppmhist [ppmf i I e ] 

DESCRIPTION 

ppmhist reads a portable pixmap as input and generates a histogram of the colors in the pixmap. 

SEE ALSO 

ppm(5), pgmhist(l) 

AUTHOR 

Copyright® 1989 byjef Poskanzer. 

3 April 1989 


ppmmake 

ppmmake— C reate a pixmap of a specified size and color 

SYNOPSIS 

ppmmake color width height 

DESCRIPTION 

ppmmake produces a portable pixmap of the specified color, width, and height. 

Thecolorcan be specified in five ways: 

■ A name, assuming that a pointer to an X 11-style color namesfilewascompiled in. 

■ An X 11-style hexadecimal specifier: ngb: r/g/b, where r, g, and b are each 1- to 4-digit hexadecimal numbers. 

■ An X 11-style decimal specifier: rgbt: r/g/b, where r, g, and b are floating-point numbers between 0 and 1. 

■ For backwards compatibility, an Old-X 11-Style hexadecimal number: #rgb, #rrggbb, #rrrgggbbb, Or#rrrrggggbbbb. 

■ For backwards compatibility, a triplet of numbers separated by commas: r,g,b, where r, g, and b are floating-point 
numbers between 0 and 1. (This style was added beforeM IT cameupwith thesimilar rgbi style) 

SEE ALSO 

ppm(5), pbmmake(l) 

AUTHOR 

Copyright® 1991 byjef Poskanzer. 

24 September 1991 


ppmmix 

ppmmix — Blend together two portable pixmaps 

SYNOPSIS 

ppmmix f adef act or ppmf i I el p p mf i I e 2 



ppmntsc 



DESCRIPTION 

ppmmix reads two portable pixmaps as input and mixes them together using the specified fade factor. The fade factor may be 
in the range from 0.0 (only ppmf i i ei 'si mage data) to 1.0 (only ppmf i i e 2 ’s image data). Anything in between gainsasmooth 
blend between thetwo images. 

The two pixmaps must have the same size. 

SEE ALSO 

ppm(5) 

AUTHOR 

Copyright® 1993 by Frank N eumann. 

16 N ovember 1993 


ppmnorm 

ppmnorm — N ormalizethecontrast in a portablepixmap 

SYNOPSIS 

ppmnorm[-bpercent N | -bvalue N][-wpercent N [ -wvalue N][ppmfile] 

DESCRIPTION 

ppmnorm reads a portable pixmap as input; normalizes the contrast by forcing the lightest pixels to white, the darkest pixels to 
black, and li nearly rescaling the ones in between; and produces a portable pixmap as output. 

It works by computing the relative gray level of each pixel as with ppmtopgm, and uses those values to scaletheRGB levels. 

N ote that this is different from using pgmnorm on the individual red, green, and blue graymaps (as produced by ppmtorgb3) 
and recombining them. 

OPTIONS 

By default, the darkest two percent of all pixels are mapped to black, and the lightest one percent are mapped to white. You 
can override these percentages by using the -bpercent and -wpercent flags, or you can specify the exact pixel values to be 
mapped by using the -bvalue and -wvalue flags. Appropriate numbers for theflags can begotten from theppmhist tool. If 
you just want to enhance the contrast, then choose values at elbows in the histogram; for example if value 29 represents3 
percent of the image but value 30 represents 20 percent, choose 30 for bvalue. If you want to lighten the image, then set 
bvalue to 0 and just fiddlewith wvalue; similarly, to darken theimage, set wvalue to maxvai and play with bvalue. 

All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

pgmnorm(l), ppmhist(l), ppm(5) 

AUTHOR 

Wilson H . Bent, Jr. (whb@usc.edu), heavily based on the pgmnorm filter byjef Poskanzer. 

7 October 1993 


ppmntsc 

ppmntsc— M ake a portable pixmap look like it is taken from an American TV show 

SYNOPSIS 

ppmntsc di mf act or [ppmfile] 
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DESCRIPTION 

ppmntsc reads a portable pi xmap as input and dims every other row of image data down by the specified dim factor. This 
factor may be in the range of 0.0 (the alternate lines are totally black) to 1.0 (original image). 

This creates an effect similar to what I saw once in the video clip "You Could beM ine" by Guns'n' Roses. In the scene I'm 
talking about you can seejohn Connor on his motorbike, looking up from the water trench (?) he's standing in. While the 
camera pulls back, the image becomes "normal" by brightening up the alternate rows of it. I thought thiswould bean 
interesting effect to try in M PEG. I did not yet check this out, however. T ry for yourself. 

SEE ALSO 

ppm(5), ppmdim(l) 

AUTHOR 

Copyright© 1993 by Frank N eumann. 

16 N ovember 1993 


ppmpat 

ppmpat — M ake a pretty pixmap 

SYNOPSIS 

ppmpat -gingham2|-g2|-gingham3j -g3j-madras|-tartan| -poles!-squigj-camo! 

-anticamo width height 

DESCRIPTION 

ppmpat produces a portable pixmap of the specified width and height, with a pattern in it. 

This program is mainly to demonstrate use of the ppmdraw routines, a simple but powerful drawing library. See the ppmdraw. h 
includefilefor more information on using these routines. Still, some of the patterns can be rather pretty. If you haveacolor 
workstation, something like ppmpat -squig 300 300 \ “ppmquant 128 " should generate a nice background. 

OPTIONS 

T he different flags specify various different pattern types: 

-gingham 2 A gingham check pattern. Can be tiled. 

-gingham3 A slightly more complicated gingham. Can betiled. 

-madras A madrasplaid. Can betiled. 

-tartan A tartan plaid. Can betiled. 

-poles Color gradients centered on randomly placed poles. M ay need to be run through ppmquant. 

-squig Squiggly tubular pattern. Can betiled. M ay need to be run through ppmquant. 

-camo Camouflage pattern. M ay need to be run through ppmquant. 

-anticamo Anticamouflage pattern; like -camo, but ultra-bright colors. M ay need to be run through ppmquant. 

All flags can be abbreviated to their shortest unique prefix. 

REFERENCES 

Some of the patterns are from "Designer's Guide to Color 3” by Jeanne Allen. 

SEE ALSO 

pnmtile(l), ppmquant(l), ppm(5) 



ppmquant 


411 


AUTHOR 

Copyright© 1989 byjef Poskanzer. 


4 September 1989 


ppmquant 

ppmquant— Quantize the colors in a portable pi xmap down to a specified number 

SYNOPSIS 

ppmquant [-floydj-fs] ncolors [ppmfile] 
ppmquant [-floydj-fs] -mapmapfile [ppmfile] 

DESCRIPTION 

ppmquant reads a portable pixmap as input. It chooses ncolors colors to best represent the image, maps the existing colors to 
the new ones, and writes a portable pixmap as output. 

The quantization method isHeckbert's"median cut.” 

Alternately, you can skip the color-choosing step by specifying your own set of colors with the -map flag. The maptiie is just 
a ppm file; it can beany shape all that matters is the colors in it. For instance, to quantize down to the 8-color IBM TTL 
color set, you might use the following: 

P3 
8 1 
255 
0 0 0 
255 0 0 
0 255 0 
0 0 255 
255 255 0 
255 0 255 
0 255 255 
255 255 255 

If you want to quantize one pixmap to use the colors in another one, just use the second oneasthemapfile. You don't have 
to reduce it down to only one pixel of each color, just use it as is. 

The - tioyd/ -fs flag enables a Floyd-Steinberg error diffusion step. Floyd-Stein berg gives vastly better results on images 
where the unmodified quantization has banding or other artifacts, especially when going to a small number of colors such as 
the preceding IBM set. FI owever, it does take substantially more CPU time, so the default is off. 

All flags can be abbreviated to their shortest unique prefix. 

REFERENCES 

"Color I mage Quantization for Frame Buffer D isplay," by Paul FI eckbert, siggraph 82 Proceedings, page 297. 

SEE ALSO 

ppmquantall(l), pnmdepth(l), ppmdither(l), ppm(5) 

AUTHOR 

Copyright© 1989,1991 byjef Poskanzer. 


12 January 1991 
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ppmquantall 

ppmquantaii — Run ppmquant on a bunch of files all at once, so they share a common colormap 

SYNOPSIS 

ppmquantall ncolors ppmfile ... 

DESCRIPTION 

ppmquantall takes a bunch of portable pixmap as input. It chooses ncoi or s colorsto best represent all oftheimages, mapsthe 
existing colorsto the new ones, and overwrites the input files with the new quantized versions 

Verbose explanation: Say you haveadozen pixmaps that you want to display on thescreen all at the same time. Your screen 
can only display 256 different colors but the pixmaps have a total of a thousand or90 different colors. For a single pixmap, 
you solve this problem with ppmquant; this script solves it for multi pie pixmaps All it does is concatenate them together into 
one big pixmap, run ppmquant on that, and then split it up into little pixmaps again. 

(N otethat another way to solve this problem is to preselect a set of colors and then use ppmquant 's -map option to separately 
quantize each pixmap to that set.) 

SEE ALSO 

ppmquant(l), ppm(5) 

BUGS 

It's a csh script, csh scripts are not portable to System V. Scripts in general are not portable to non-U NIX environments. 

AUTHOR 

Copyright© 1991 byjef Poskanzer. 

27 July 1990 


ppmqvga 

ppmqvga — 8-plane quantization 

SYNOPSIS 

ppmqvga [ options ] [ input file ] 

DESCRIPTION 

ppmqvga quantizes PPM files to eight planes, with optional Floyd-Steinberg dithering. Input isa PPM file from the file 
named, or standard input if no file is provided. 

OPTIONS 

-d dither Apply Floyd-Steinberg dithering to the data 

-q quiet Produces no progress reporting, and no terminal output unless an error occurs. 

-v verbose Produces additional output describing the number of colors found, and some information on the resulting 

mapping. M ay be repeated to generate loads of internal table output, but generally only useful once. 

EXAMPLES 

ppmqvga -d my_image.ppm ] ppmtogif xny_image.gif 


tgatoppm zombie.tga \ ppmqvga | ppmtotif > zombie.tif 
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SEE ALSO 

ppmquant 

DIAGNOSTICS 

Error messages if problems; various levels of optional progress reporting. 

AUTHORS 

Original by Lyle Rains (irains@netcom.com) asppmq256 and ppmq256fs combined; documented and enhanced by Bill Davidsen 

(davidsen@crd.ge.com). 

COPYRIGHT 

Copyright© 1991,1992 by Bill Davidsen, all rights reserved. Theprogram and documentation may be freely distributed by 
anyone in source or binary format. Please clearly note any changes. 

Local 


ppmrelief 

ppmreiiet — Run a Laplacian relief filter on a portable pixmap 

SYNOPSIS 

ppmrelief [ppmf i I e ] 

DESCRIPTION 

ppmrelief reads a portable pixmap as input, does a Laplacian relief filter, and writes a portable pixmap as output. 

The Laplacian relief filter is described in Beyond Photography by H olzmann, equation 3.19. It's a sort of edge-detection. 

SEE ALSO 

pgmbentley(l), pgmoil(l), ppm(5) 

AUTHOR 

Copyright© 1990 by Wilson Bent (whb@hoh- 2 .att.com). 

11 January 1991 


ppmshift 

ppmshift— Shift I ines of a portable pixmap left or right by a random amount 

SYNOPSIS 

ppmshift shift [ppmf i I e ] 

DESCRIPTION 

ppmshift reads a portable pixmap as input and shifts every row of image data to the left or right by a certain amount. The 
shi ft parameter determines by how many pixels a row is to be shifted at most. 

Another one of those effects I intended to useforMPEG tests. Unfortunately, this program will not help me here-it creates 
patterns that are too random to be used for animations. Still, it might give interesting results on still images. 
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EXAMPLE 

Check this out: Save your favorite model's picture from something likeait.binaries.pictures.supermodeis (okay, or from 
any other picture source), convert it to ppm, and process it likethis, assuming the picture is 800x600 pixels: 

1. Take the upper half and leave it like it is: pnmcut 0 0 800 300 cs.ppm >upper.ppm. 

2. Takethe lower half, flip it upside down, dim it, and distort it a little: pnmcut 0 300 800 300 cs.ppm ; pnmtiip -tb | 

ppmdim 0.7 | ppmshift 10 >lower.ppm. 

3. C oncatenate the two pieces: pnmcat -tb upper.ppm lower.ppm >newpic.ppm. 

The resulting picture looks I ike the image being reflected on a water surface with slight ripples. 

SEE ALSO 

ppm(5), pnmcut(l), pnmflip(l), ppmdim(l), pnmcat(l) 

AUTHOR 

Copyright® 1993 by Frank N eumann. 

16 N ovember 1993 


ppmspread 

ppmspread— D isplace a portable pixmap's pixels by a random amount 

SYNOPSIS 

ppmspread amount [ppmfile] 

DESCRIPTION 

ppmspread reads a portable pi xmap as input and moves every pixel around a bit relative to its original position, amount 
determines by how many pixels a pixel isto be moved around at most. 

Pictures processed with this filter will seem to be somewhat dissolved or unfocussed (although they appear more coarse than 
images processed by something likepnmconvoi). 

SEE ALSO 

ppm(5), pnmconvol(l) 

AUTHOR 

Copyright® 1993 by Frank N eumann. 

16 N ovember 1993 


ppmtoacad 

ppmtoacad— C onvert portable pi xmap to AutoCAD database or slide 

SYNOPSIS 

ppmtoacad [-dxb][-poly][-background col our][-white][-aspect ratio][-8 ][ppmfi Ie] 

DESCRIPTION 

ppmtoacad reads a portable pixmap as input. Produces an AutoCAD slide file or binary database import (DXB) file as output. 
If no ppmfile is specified, input is read from standard input. 
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OPTIONS 

-dxb An AutoCAD binary database import (DXB) file is written. This file is read with theDXBiN 

command and, once loaded, becomes part of the AutoCAD geometrical database and can be 
viewed and edited like any other object. Each sequence of identical pixels becomes a separate object 
in the database; thiscan result in very largeAutoCAD drawingfiles. H owever, if you wantto trace 
over a bitmap, it lets you zoom and pan around the bitmap as you wish. 

-poly Ifthe-dxb option isnot specified, theoutput of ppmtoacad isan AutoCAD slidefile N ormally, 

each row of pixels is represented by an AutoCAD line entity. If -poly is selected, the pixels are 
rendered as filled polygons. If the slide is viewed on a display with higher resolution than thesource 
pixmap, thiswill cause the pixelsto expand instead of appearing as discrete lines against thescreen 
background color. Regrettably, this representation yields slide files that occupy more disc space and 
take longer to display. 

-background color MostAutoCAD display drivers can be configured to use any available color as the screen back¬ 
ground. Some users prefer a black screen background, others white, while splinter groups advocate 
burnt ocher, tawny puce, and shocking gray. D iscarding pixels whose closest AutoCAD color 
representation is equal to the background color can substantially reduce the size of the AutoCAD 
database or slidefile needed to represent a bitmap. If no - background color is specified, thescreen 
background color isassumed to be black. Any AutoCAD color number may be specified as the 
screen background; color numbers are assumed to specify the hues defined in the standard 
AutoCAD 256-color palette. 

-white Becausemany AutoCAD users choose a white screen background, thisoption isprovided asa 

short-cut. Specifying -white is identical in effect to -background i. 

-aspect rati o If the source pixmap had nonsquare pixels, the ratio of the pixel width to pixel height should be 

specified as ratio. The resulting slide or DXB file will be corrected so that pixels on the AutoCAD 
screen will be square. For example, to correct an image made for a 320x200 VGA/M CGA screen, 
specify -aspect 0.8333. 

-8 Restrictsthe colors in theoutput file to the eight RGB shades. 

All flags can be abbreviated to their shortest unique prefix. 

BUGS 

AutoCAD hasafixed palette of 256 colors, distributed alongthehue, lightness, and saturation axes. Pixmaps that contain 
many nearly identical colors, or colors not closely approximated by AutoCAD's palette, may be poorly rendered. 

ppmtoacad works best if the system displaying its output supports the full 256 color AutoCAD palette. M onochrome, 

8 -color, and 16-color configurations will produce less than optimal results 

When creating a DXB file or a slide file with the - poly option, ppmtoacad finds both vertical and horizontal runs of identical 
pixels and consolidates them into rectangular regions to reduce the size of the output fi le This is effective for images with 
large areas of constant color, but it’s no substitute for true raster to vector conversion. In particular, thin diagonal lines are 
not optimized at all by this process. 

Output files can be huge. 

SEE ALSO 

AutoCAD Reference M anual: "Slide File Format" and "Binary Drawing Interchange (DXB) Files"; ppm(5) 

AUTHOR 

John Walker 
Autodesk SA 

Avenue desChamps-M ontants 14b 
C FI -2074 M ARIN 

Suisso'Schweiz/Svi zzera/ Svizra/ Swi tzerl an d 
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Usenet: kelvin?Autodesk.com 

Fax: 038/33 88 15 

Voice 038/33 76 33 

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is 
hereby granted, without any conditions or restrictions. This software is provided "as is" without express or implied warranty. 

AutoCAD and Autodesk are registered trademarks of Autodesk, Inc. 

10 October 1991 


ppmtobmp 

ppmtobmp— Convert a portablepixmap into a BM P file 

SYNOPSIS 

ppmtobmp [-wi ndows ] [-os2 ] [ppmf i I e ] 

DESCRIPTION 

ppmtobmp reads a portable pixmap as input and produces a M icrosoft Windows or OS/2 BMP file as output. 

OPTIONS 

-windows T el Is the program to produce a M icrosoft W indows BM P file 
-os 2 T el Is the program to produce an OS/2 BM P file. (This is the default.) 

All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

bmptoppm(l), ppm(5) 

AUTHOR 

C opyright® 1992 by D avid W. Sanderson. 

26 October 1992 


ppmtogif 

ppmtogif — C onvert a portable pixmap into a GIF file 

SYNOPSIS 

ppmtogif [-interlace][-sort][-map mapf i I e][-transparent col or ][ppmf i I e] 

DESCRIPTION 

ppmtogif reads a portable pixmap as input and producesaGIF file as output. 

OPTIONS 

T el Is the program to produce an interlaced GIF file. 

ProducesaGIF file with a sorted colormap. 

Uses the colors found in themapf i i e to create the colormap in theGIF file, instead of thecolors 
from ppmf iie. Themapf i i e can beany ppm file; all that matters is the colors in it. If the colors in 


-interlace 

-sort 

-map mapf i I e 



ppmtoicr 

ppmf iie do not match those in inaptue, the/ are matched to a "best match.” A (much) better result 
can be obtained by using the following filter in advance: 
ppmquant -floyd -map map-file 

-transparent color M ark the given color astransparent in theGIF file. T hecolor is specified as i n ppmmake(l). Note 
that this option outputs a GIF89a format file, which might not be understood by your software. 

All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

giftoppm(l), ppmquant(l), ppm(5) 

AUTHOR 

Based on gifencod by David Rowley (mgardi@watdcsu.waterioo.edu). Lempel-Zivcompression based on compress. 

Copyright© 1989 byjef Poskanzer. 

30Junel993 

ppmtoicr 

ppmtoicr— Convert a portablepixmap into N CSA ICR format 

SYNOPSIS 

ppmtoicr [-windowname name][-expand expand][- display di spi ay][-rle][ppmf i I e] 

DESCRIPTION 

ppmtoicr reads a portable pixmap file as input and produces an N CSA Telnet Interactive Color Raster graphic file as output. 
If ppmtiie is not supplied, ppmtoicr will read from standard input. 

Interactive Color Raster (ICR) is a protocol for displaying raster graphics on workstation screens. The protocol is imple¬ 
mented in N CSA Telnet for the M acintosh version 2.3. The ICR protocol shares characteristics of the T ektronix graphics 
terminal emulation protocol. For example escape sequences are used to control the display. 

ppmtoicr will output the appropriate sequences to createawindow of the dimensions of theinput pixmap, create a col ormap 
of up to 256 colors on the display, then load the picture data into the window. 

N ote that there is no icrtoppm tool; this transformation is oneway. 

OPTIONS 

-windownamename Output will be displayed in name. (Default is to useppm-fiie or "untitled" if standard input is read.) 
-expandexpand Output will be expanded on display by factor expand. (For example, a value of 2 will cause four pixels to be 
displayed for every input pixel.) 

-dispiaydi s pi ay Output will be displayed on screen numbered di s pi ay. 

-rie Use run-length encoded format for display. (Thiswill nearly always result in a quicker display, but may 

skew thecolormap.) 

EXAMPLES 

T his displays a ppm file using the protocol: 

ppmtoicr ppmfile 

Thiswill createawindow named ppmtiie on the display with the correct dimensions for ppmtiie, create and download a 
colormap of up to 256 colors, and download the picture into the window. The same effect may be achieved by the following 
sequence: 
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ppmtoicr ppmfile > filename 
cat filename 

T o display a GIF file using the protocol in a window titled after the input file, zoom the displayed image by a factor of 2, 
and run-length encode the data: 

giftoppm giffile | ppmtoicr -w giffile -r -e 2 

BUGS 

The protocol uses frequent mush calls to speed up display. If theoutput is saved to afilefor later display via cat, drawing 
will be much slower. In either case, increasing the Blocksize limit on the display will speed up transmission substantially. 

SEE ALSO 

ppm(5) 

NCSA Telnet for the M adntosh, U niversity of Illinois at Urbana-Champaign (1989) 

AUTHOR 

Copyright© 1990 by Kanthan Pillay (svpuiay@Princeton.EDu), Princeton University Computing and Information Technol- 

°gy 

30 July 1990 


ppmtoilbm 

ppmtoiibm— Convert a portablepixmap into an ILBM file 

SYNOPSIS 

ppmtoilbm [-maxplanes|-mp N][-fixplanes| -fp N][-ham6|-ham8][-dcbits-dcplanesrgb] 

[-normalj-hamif|-hamforce|-24ifJ-24forcej -dcif[-deforce!-cmaponly] [-ecs|-aga] 

[- compress!-nocompress][-cmethod type][-mapppmfile] [-savemem][ppmfile] 

DESCRIPTION 

ppmtoilbm reads a portable pixmap as input and produces an ILBM file as output. Supported ILBM types are the following: 

Normal ILBM swith 1-16 planes 
Amiga HAM with 3-16 planes 
24-bit 

C olormap (bmhd and cmap chunk only, nPianes = 0 ) 

Unofficial direct color 1-16 planesfor each color component 

Chunks written: bmhd, cmap, camg (only for HAM ), body (not for colormap files) unofficial dcol chunk for direct color ILBM 

OPTIONS 

Options marked with (*) can be prefixed with no, for example, -nobamit. All options can be abbreviated to their shortest 
unique prefix. 

-maxplanes j ■ mp n (default 5, minimum 1, maximum 16) M aximum planes to write in a normal I LB M . If the 

pixmap does not fit into n planes, ppmtoilbm writes a HAM file (if -hamif is used), a 24-bit 
fi le (if -24if isused), a direct color file (if -dcif isused). or aborts with an error. 

-fixplanes | -fp n (min 1, max 16) I f a normal I LB M is written, it will haveexactlyn planes. 

-hambits | -hampianes n (default 6, min 3, max 16) Select number of planes for H AM picture. T hecurrent Amiga 
hardware supports 6 and 8 planes, so for now you should only use thisvalues. 
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-normal (default) 

-hamif (*), -24if (*), 

-dcif (*) 

-hamforce (*), -24force (*), 
-deforce (*) 

-debits | -deplanes r g b 

-ecs (default) 

-aga 

-ham6 

-ham8 

•compress (*) (default), 
-cmethod none[byterunl 


-map ppmf i I e 

-cmaponly 

-savemem 


Turns off -hamif/ - 24if /-dcif, -hamforce/-24force/-deforce and -cmaponly. AI SO sets 
compression type to byterunl. 

W rite a H AM /24-bit/direct color fi le if the pixmap does not fit i nto maxpianes planes. 

W rite a H AM /24-bit/direct color file. 

(default5, min 1, max 16). Select number of bits for red, green, and blue in a direct color 
ILBM. 

Shortcut for: -hamplanes 6 -maxpianes 5 
Shortcut for: -hamplanes 8 -maxpianes 8 
Shortcut for: -hamplanes 6 -hamforce 
Shortcut for: -hamplanes 8 -hamforce 

Compress the body chunk. The default compression method is byterunl. Compression 
requires building the ILBM imagein memory; turning compression off allows stream¬ 
writing of the image, but the resulting file will usually be 30 percent to 50 percent larger. 
Another alternative is the -savemem option; this will keep memory requirements for 
compression at a minimum, but isvery slow. 

Writea normal ILBM using the colors in ppmf i i e asthecolormap. T hecolormap file also 
determines the number of planes; a -maxpianes or -fixpianes option is ignored. 

W rite a colormap file: only bmhd and cmap chunks, no body chunk, nPianes = 0. 

Seethe -compress option. 


BUGS 

HAM pictures will always get a grayscale colormap; a real color selection algorithm might give better results. On the other 
hand, this allows row-by-row operation on HAM images, and all HAM images of the same depth (number of planes) sharea 
common colormap, which is useful for building HAM animations. 

REFERENCES 

Amiga ROM Kernel Reference M anual— D a/ices (Third Edition), Addison Wesley, ISBN 0-201-56775-X 

SEE ALSO 

ppm(5), ilbmtoppm(l) 

AUTHORS 

Copyright© 1989 byjef Poskanzer; modified October 1993 by Ingo Wilken (ingo.wiiken@infbrmatik.uni-bidenburg.de). 

31 October 1993 


ppmtomap 

ppmtomap— Extract all colors from a portable pixmap 

SYNOPSIS 

ppmtomap [-sort][-square][ppmf i I e] 

DESCRIPTION 

ppmtomap reads a portable pixmap as input and produces a portable pixmap as output, representing a colormap of the input 
file. All n different colors found are put in an N XI portable pixmap. This colormap file can be used as a mapfileforppmquant 
Or ppmtogif. 
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OPTIONS 

-sort Produces a portable pixmap with thecolorsin somesorted order 

-square Produces a (more or less) square output file instead of putting all colors on the top row 

All flags can be abbreviated to their shortest unique prefix. 

WARNING 

If you want to use the output file as a mapfilefor ppmtogit, you first have to do a ppmquant 256 because ppmtomap is not 
limited to 256 colors (but to 65536). 

SEE ALSO 

ppmtogif(l), ppmquant(l), ppm(5) 

AUTHOR 

M arcel W ijkstra (wijkstra@fwi.uva.nl) 

Copyright© 1989 byjef Poskanzer. 

11 August 1993 


ppmtomitsu 

ppmtomitsu— Convert a portable pixmap to a M itsubishi S340-10 file 

SYNOPSIS 

ppmtomitsu [-sharpness val ][-enlarge val ][-media st r i ng][-copy val ] 
[ -dpi300] [ -tiny] [ppmf i I e ] 


DESCRIPTION 


ppmtomitsu reads a portable pixmap as input and converts it into a format suitable to be printed by aM itsubishi S340-10 
printer, or any other M itsubishi color sublimation printer. 


TheM itsubishi S340-10 Color Sublimation printer supports 24-bit color. I mages of the available sizes take so long to 
transfer that there is a fast method, employing a lookup table that ppmtomitsu will use if there is a maximum of 256 colors in 
the pixmap. ppmtomitsu will try to position your image to the center of the paper, and will rotate your image for you if xsize 
is larger than ysize. If your image is larger than the media allows, ppmtomitsu will quit with an error message. (We decided 
that the media were too expensive to have careless users produce misprints) After data transmission has started, the job can't 
be stopped in a sane way without resetting the printer. The printer understands putting together images in the printer's 
memory; ppmtomitsu doesn't utilize this as pnmcat and so on provide the same functionality and let you view the result 
onscreen, too. TheS340-10 is the lowest common denominator printer; for higher resolution printers, there's the dpi30@ 
option. The other printers also support higher values for enlarge eg, but I don't think that's essential enough to warrant a 
change in the program. 


-sharpness 1 -4 
-enlarge 1 -3 
-media A, A4, AS, A4S 


-copy 1-9 
-dpi300 


Sharpness designation. Default isto use the current sharpness. 

Enlarge by a factor; default is i (no enlarge) 

Designatethe media you're using. Default isim x 1350 , which will fit on any media. A is 1216 x 
1350 , A4 is 11 84 x 1452 , AS is 1216 x 1650 , and A4S is 11 84 x 1754 . A warning: If you specify a 
different media than the printer currently has, the printer will wait until you put in the correct 
media or switch it off. 

The number of copies to produce. Default is i. 

Double the number of allowed pixelsfor a S3600-30 Printer in S340-10 compatibility mode. (The 
S3600-30 has300dpi.) 
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-tiny M emory-safing, but always slow. The printer will get the data line-by-line in 24-bit. It's probably a 

good idea to use this if your machine starts paging a lot without this option. 


REFERENCES 

M itsubishi Sublimation Full Color Printer S340-10; Specifications of Parallel I nterface LSP-F0232F 

SEE ALSO 

ppmquant(l), pnmscale(l), ppm(5) 

BUGS 

We didn't find any—yet. Besides, they're called features anyway:-) If you should find one, please e-mail me at the following 
address. 

AUTHOR 

Copyright© 1992,1993 by S. PetraZeidler, M PIFR Bonn, Germany (spz@speckiec.mpitr-bonn.mpg.de). 

29 January 1992 


ppmtopcx 

ppmtopcx— Convert a portablepixmap into a PCX file 

SYNOPSIS 

ppmtopcx [ppmf i I e ] 

DESCRIPTION 

ppmtopcx reads a portable pixmap as input and producesaPCX file as output. 

SEE ALSO 

pcxtoppm(l), ppm(5) 

AUTHOR 

C opyright © 1990 by M ichael D avidson. 

9 April 1990 


ppmtopgm 

ppmtopgm— C onvert a portable pixmap into a portable graymap 

SYNOPSIS 

ppmtopgm [ppmf i I e] 

DESCRIPTION 

ppmtopgm reads a portable pixmap as input and produces a portable graymap as output. T he quantization formula used is 
.299 r+.587 g+ .114 b. 

N otethat although thereisapgmtoppm program, it is not necessary for simple conversions from pgm to ppm, because any ppm 
program can read pgm (and pbm ) files automagically, pgmtoppm is for colorizing a pgm file. Also, seeppmtorgb3 for a different 
way of converti ng color to gray. 
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QUOTE 

C old-hearted orb that rules the night 
Removes the colors from oursght 
Red is gray, and yellow white 
Butwedecidewhich isright 
And which isa quantization error. 

SEE ALSO 

pgmtoppm(l), ppmtorgb3(l), rgb3toppm(l), ppm(5), pgm(5) 

AUTHOR 

Copyright© 1989 byjef Poskanzer. 

23 December 1988 


ppmtopil 

ppmtopii — C onvert a portable pixmap into an Atari D egas PI 1 file 

SYNOPSIS 

ppmtopil [ppmf i I e ] 

DESCRIPTION 

ppmtopii reads a portable pixmap as input and produces an Atari D egas PI 1 file as output. 

SEE ALSO 

piltoppm(l), ppm(5), pbmtopi3(l), pi3topbm(l) 

AUTHOR 

Copyright© 1991 by Steve Belczyk (seb3@gte.com) and J ef Poskanzer. 

19 July 1990 


ppmtopict 

ppmtopict— C onvert a portable pixmap into a M acintosh PICT file 

SYNOPSIS 

ppmtopict [ppmf i I e ] 

DESCRIPTION 

ppmtopict reads a portable pixmap as input and produces a Macintosh PICT file as output. 

The generated file is only the data fork of a picture. You will need a program such asmcvert to generate a M acbinary or a 
BinH ex fi le that contai nsthe necessary information to identify thefileasa PICT file to M acOS. 

Even though PICT supports2 and 4 bits per pixel, ppmtopict always generates an 8-bits-per-pixel file. 

BUGS 

The picture size field is only correct if the output is to a file because writing into this field requires seeking backwards on a 
file. H owever, the PICT documentation seems to suggest that this field is not critical anyway because it is only the lower 16 
bits of the picture size. 
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SEE ALSO 

picttoppm(l), ppm(5), mcvert(l) 

AUTHOR 

Copyright® 1990 by Ken Yap (ken@cs.rocester.edu). 

15 April 1990 


ppmtopj 

ppmtopj— Convert a portable pixmap to an HP PaintJet file 

SYNOPSIS 

ppmtopj [-gamma val ][-xpos val ][-ypos val ][ - back dark jlite][-rle][-center] 

[-render none|snap!bwjdither[diffuse|monodither|monodiffuse|clusterdither| 
monoclusterdither][ppmf i I e] 

DESCRIPTION 

ppmtopj reads a portable pixmap as input and converts it into a format suitable to be printed by an H P PaintJet printer. 

For best results, the i nput file should bein 8-color RGB form; thatis, it should have only the eight binary combi nations of 
full-on and full-off primaries. You could get this by sending the input file through ppmquant -map with amapfilesuch as 

P3 
8 1 
255 

000 2550 0 02550 0 0 255 

255 255 0 255 0 255 0 255 255 255 255 255 

0 r else you COUld Use ppmdither -red 2 -green 2 -blue 2. 

OPTIONS 

-rle 
-back 

-render al g 
-gamma i nt 
-center 
-xpos pos 
-ypos pos 

REFERENCES 

HP PaintJetXL Color GraphicsPrinter User'sCuide 

SEE ALSO 

pnmdepth(l), ppmquant(l), ppmdither(l), ppm(5) 

BUGS 

M ost of the options have not been tested because of the price of the paper. 

AUTHOR 

C opyright® 1991 by C hristos Zoulas. 


Run-length encode the image. (Thiscan result in larger images.) 

Enhance the foreground by indicating if the background is light or dark compared to the foreground. 
Use an internal rendering algorithm (default dither). 

G amma correct the i mage usi ng the integer parameter as a gamma (default 0 ). 

Center theimageto an 8.5 by 11 page. 

Movebypos pixels in the x direction. 

Movebypos pixels in they direction. 


13 July 1991 
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ppmtopjxl 

ppmtopjxi— Convert a portable pi xmap into an H P PaintJet XL PC L file 

SYNOPSIS 

ppmtopjxl [-nopack] [-gamma <n> ] [-presentation] [-dark] [-diffuse] 

[-cluster] [-dither] [-xshift <s> ] [-yshift <s> ] [-xshift <s> ] [-yshift <s> ] 

[-xsize|-width|-xscale <s> ] [-ysize|-height|-yscale <s> ] [ppmfile] 

DESCRIPTION 

ppmtopjxl reads a portable pi xmap as input and produces a PC L file suitable for printing on an H P PaintJet XL printer as 
output. 

The generated file is not suitable for printing on a normal Printjet printer. The -nopack option generates a file that does not 
use the normal TIFF 4.0 compression method. Thisfile might be printable on a normal PaintJet printer (not an XL). 

The -gamma option sets the gamma correction for the image. The useful range for the PaintJet XL is approximately 0.6 
to 1.5. 

The rendering algorithm used for images can be altered with the -dither, -cluster, and -diffuse options. These options 
select ordered dithering, clustered ordered dithering, or error diffusion, respectively. The -dark option can beused to 
enhance images with a dark background when they are reduced in size. The -presentation option turns on presentation 
mode in which two passes are made over the paper to increase ink density. This should beused only for images where 
quality is critical. 

The image can be resized by setting the -xsize and -ysize options The parameter to either of these options is interpreted as 
the number of dots to set the width or height to, but an optional dimension of pt (points), dp (deci points), in (inches), or cm 
(centimeters) may be appended. If only onedimension is specified, the other wi II be scaled appropriately. 

The options -width and -height are synonyms of -xsize and -ysize. 

T he -xscale and -yscale options can alternatively be used to scale the image by a simple factor. 

T he image can be shifted on the page by usi ng the -xshift and -yshift options. T hese move the image the specified 
dimensions right and down. 

SEE ALSO 

ppm(5) 

AUTHOR 

Angus Duggan 

14 March 1991 


ppmtopuzz 

ppmtopuzz— C onvert a portable pi xmap into an Xll puzzle file 

SYNOPSIS 

ppmtopuzz [ppmf i I e ] 

DESCRIPTION 

ppmtopuzz reads a portable pi xmap as input and produces an Xll puzzle file as output. A puzzle file is for use with the puzzle 
program included with theXll distribution; puzzle's -picture flag lets you specify an image file 
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SEE ALSO 

ppm(5), puzzle(l) 

AUTHOR 

Copyright® 1991 byjef Poskanzer. 

22 August 1990 


ppmtorgb3 

ppmtorgb3 — Separate a portable pixmap into three portable graymaps 

SYNOPSIS 

ppmtorgb3 [p p mf i I e] 

DESCRIPTION 

ppmtorgb3 reads a portable pi xmap as input and writes three portable graymaps as output, one each for red, green, and blue. 

The output filenames are constructed by taking the input filename stripping off any extension, and appending .red, .grn, 
and .blu. For example, separating lenna. ppm would result in lenna.red, lenna.grn, and lenna.blu. If the input comes from 
stdin, the names are noname. red, noname .grn, and noname .blu. 

SEE ALSO 

rgb3toppm(l), ppmtopgm(l), pgmtoppm(l), ppm(5), pgm(5) 

AUTHOR 

Copyright® 1991 byjef Poskanzer. 

10 January 1991 


ppmtosixel 

ppmtosixei— Convert a portablepixmap into DEC sixel format 

SYNOPSIS 

ppmtosixel [ -raw] [ -margin] [ppmf i I e ] 

DESCRIPTION 

ppmtosixel reads a portable pixmap as input and produces sixel commands (SIX) as output. The output is formatted for color 
printing, for example, fora D EC LJ250 color inkjet printer. 

If RGB values from the PPM file do not havemaxvai=i 00 , the RGB values are rescaled. A printer control header and a color 
assignment table begin the SIX file I mage data is written in a compressed format by default. A printer control footer ends 
the image file. 

OPTIONS 

-raw If specified, each pixel will beexplicitly described in theimagefile. If -raw is not specified, output will default to 
compressed format in which identical adjacent pixels are replaced by repeat pixel commands. A raw file is often 
an order of magnitude larger than a compressed file and prints much slower. 

-margin If -margin is not specified, the image will start at the left margin (of thewindow, paper, or whatever). If -margin is 
specified, a 1.5 inch left margin will offset the image. 
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PRINTING 

Generally, sixd fi les must reach the printer unfiltered. Usetheipn -x option or cat filename > /dev/tty 0 ?. 

BUGS 

Upon rescaling, truncation of the least significant bits of RGB values may result in poor color conversion. If the original 
PPM maxvai was greater than 100, rescaling also reduces theimage depth. Whilethe actual RGB values from the ppm file are 
more or less retained, the color palette of the LJ 250 may not match the colors on your screen. This seems to be a printer 
limitation. 

SEE ALSO 

ppm(5) 

AUTHOR 

Copyright© 1991 by Rick Vinci. 

26 April 1991 


ppmtotga 

ppmtotga— Convert portablepixmap into aTrueVision Targafile 

SYNOPSIS 

ppmtotga [-mono!-cmapj-rgb][-norle][ppmf i I e] 

DESCRIPTION 

ppmtotga reads a portable pixmap as input and produces a T rueV ision T arga file as output. 

OPTIONS 

-mono Forces T arga file to be of type 8-bit monochrome. Input must be a portable bitmap or a portable graymap. 

-cmap Forces T arga file to be of type 24-bit colormapped. Input must be a portable bitmap, a portable graymap, ora 

portable pixmap containing no more than 256 distinct colors 
-rgb ForcesT argafileto be of type 24-bit unmapped color. 

-none D isables run-length encoding, in case you have a T arga reader that can't read run-length encoded files. 

All flags can be abbreviated to their shortest unique prefix. If no file type is specified, the most highly constained compatible 
type is used, where monochrome is more constained than colormapped, which is in turn more constained than unmapped. 

BUGS 

Does not support all possibleT arga file types. Should really beinpnm, not ppm. 

SEE ALSO 

tgatoppm(l), ppm(5) 

AUTHOR 

C opyright© 1989,1991 by M ark Shand and J ef Poskanzer. 


28 October 1991 
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ppmtouil 

ppmtouii— Convert a portablepixmap into a M otif UIL icon file 

SYNOPSIS 

ppmtouil [-name ui I name ] [ppmf i I e ] 

DESCRIPTION 

ppmtouil reads a portable pixmap as input and produces a M otif UIL icon file as output. 

If the program was compiled with an rgb database specified, and an RGB value from the ppm input matches an RGB value 
from the database, then the corresponding color name mnemonic is printed in theUIL'scolormap. If no rgb database was 
compiled in, or if the RGB values don't match, then the color will be printed with the#RGB, #rrggbb, #rrrgggbbb, or 
#rrrrggggbbbb hexadecimal format. 

OPTIONS 

-name Allows you to specify the prefix string that is printed in the resulting U IL output. If not specified, it will default to 
the filename (without extension) of the ppmf iie argument. If -name is not specified and no ppmfiie is specified 
(that is, piped input), the prefix string will default to the string "noname 11 . 

All flags can be abbreviated to their shortest unique prefix. 

SEE ALSO 

ppm(5) 

AUTHOR 

Converted byjef Poskanzerfrom ppmtoxpm. c, which is copyright® 1990 by M ark W. Snitily. 

31 August 1990 


ppmtoxpm 

ppmtoxpm— Convert a portable pixmap into an Xll pixmap 

SYNOPSIS 

ppmtoxpm [-name <xpmname>] [-rgb <rgb-textfile>][ <pp mf i I e>] 

DESCRIPTION 

ppmtoxpm reads a portable pixmap as input and produces an Xll pixmap (version 3) as output that can be loaded directly by 
theXPM library. 

The - name option allowsyou to specify the prefix string which is printed in the resulting X PM output. If not specified, it will 
default to the filename (without extension) of the ppmfiie argument. If -name is not specified and ppmfiie is not specified 
(that is, piped input), the prefix string will default to the string "noname". 

The -rgb option allowsyou to specify an Xll rgb text file for the lookup of color name mnemonics. This RGB textfileis 
typically the /usr/iib/xn /rgb.txt of the M IT Xll distribution, but any file using the same format may be used. When 
specified and an RGB value from the ppm input matches an RGB value from the <rgb- textf iie>, then the corresponding 
color name mnemonic is printed in theXPM 'scolormap. If -rgb is not specified, or if the RGB values don't match, then the 
color will be printed with the#RGB, #rrggbb, #rrrgggbbb, or #rrrrggggbbbb hexadecimal format. 

All flags can be abbreviated to their shortest unique prefix. 
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For example, to convert the file dot (found in /usr/inciude/xn/bitmaps), from xbm to xpm, you could specify 

xbmtopbm dot | ppmtoxpm -name dot 

or, with an rgb text file (in the local directory) 

xbmtopbm dot j ppmtoxpm -name dot -rgb rgb.txt 

BUGS 

An option to match the closest (rather than exact) color name mnemonic from the rgb text would be a desirable enhance¬ 
ment. 

T runcation of the least significant bits of an RGB value may result in nonexact matches when performing color name 
mnemonic lookups. 

SEE ALSO 

ppm(5) 

XPM Manual byArnaud LeHors(lehors@mirsa.inria.fr). 

AUTHOR 

Copyright © 1990 by M ark W. Snitily. T histool was developed for Schlumberger Technologies, ATE D ivision, and with 
their permission is being made avail able to the public with the above copyright notice and permission notice. 

U pgraded to XPM 2 by Paul B reslaw, M ecasoft SA, Zurich, Switzerland (paui@mecazh,uu.ch); Thu, N ov8, 16:01:17, 1990. 

U pgraded to XPM version 3 byArnaud leH ors (iehors@mirsa.inria.tr). 

9 April 1991 
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ppmtoyuv— Convert a portable pixmap into an Abekas YU V file 

SYNOPSIS 

ppmtoyuv [ppmfile] 

DESCRIPTION 

ppmtoyuv reads a portable pixmap as input and produces an Abekas YU V file as output. 

SEE ALSO 

yuvtoppm(l), ppm(5) 

AUTHOR 

M arc Boucher (<marc@Postimage.coM>), based on Example Conversion Program, A 60/A 64 Digital Video Interface M anual, 
page 69. Copyright® 1991 by D H D Post I mage Inc. Copyright® 1987 by Abekas Video Systems Inc. 

25 March 1991 


ppmtoyuvsplit 

ppmtoyuvspiit— Convert a portable pixmap into three subsampled rawYUV files 

SYNOPSIS 

ppmtoyuvsplit basename [ppmfile] 



pr 



DESCRIPTION 

ppmtoyuvsplit reads a portable pixmap as input and produces three raw files— basename.V, basename.U, and basename.V— as 
output. These files are the subsampled rawYUV representation of the input pixmap, as required by theStanford M PEG 
code. The subsampling is done by arithmetic mean of 4 pixels colors into one The YU V values are scaled according to 
CCIR.601, as assumed by M PEG. 

SEE ALSO 

mpeg(l), ppm(5) 

AUTHOR 

Copyright© 1993 byAndreBeck (AndreBeck@IRS.Inf.TU-Dresden.de). Based on ppmtoyuv.c. 

9 September 1993 


pr 

pr— C onvert text fi les for printi ng 

SYNOPSIS 

pr [+PAGE] [-COLUMN] [-abcdfFmrtv] [-e[in-tab-char[in-tab-width]]] [-h header] 
[-i[out-tab-char[out-tab-width]]] [-1 page-length] [-n[number-separator[digits]]] 

[-0 left-margin] [-s[column-separator]] [-w page-width] [--help] [-- version] [file...] 


DESCRIPTION 

This manual page documents the GN U version of pr. pr prints on the standard output a paginated and optionally 
multicolumn copy of the text files given on the command line, or of the standard input if no files are given or when the 
fi lename - is encountered. Form feeds in the input cause page breaks i n the output. 


OPTIONS 

PAGE 

-COLUMN 


-a 

-b 

-c 

-d 

-e[in-tab-char 
[in-tab-width]] 
-F, -f 
-h header 
--help 

-i[out-tab-char 
[out-tab-width]] 
-1 page-1 engt h 

-m 


Begin printing with page page. 

Produce coLUMN-column output and print columns down. The column width is automatically 
decreased as column increases; unless you usethe-w option to increase thepagewidth as well, this 
option might cause some columns to be truncated. 

Print columns across rather than down. 

Balance columns on the last page. 

Print control characters using hat notation (for example, “G); print other unprintable characters in 
octal backslash notation. 

D ouble-space the output. 

Expand tabs to spaces on input. Optional argument in-tab-char is the input tab character, default 
tab. Optional argument in-tab-width is the i nput tab character's width, defaults. 

Use a form feed instead of newlines to separate output pages. 

Replace the filename in the header with thestring header. 

Print a usage message and exit with a nonzero status. 

Replace spaces with tabs on output. Optional argument out-tab-char isthe output tab character, 
default tab. Optional argument out-tab-width is the output tab character's width, default s. 

Set the page length to page - 1 engt h lines. The default is 66. If page - 1 engt h is less than 10, the 
headers and footers are omitted, as if the-t option had been given. 

Print all files in parallel, one in each column. 
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-n[number-separator 
[digits]] 

-o I ef t■ mar gi n 

-r 


-s[coI umn-separator ] 
-t 


-v 

--version 
-w page-width 


Precede each column with a linenumber; with parallel files, precedeeach linewith alinenumber. 
Optional argument number-separator is the character to print after each number, default tab. 
Optional argument digits is the number of digits per line number, defaults. 

Offset each linewith a margin i eft-margi n spaces wide. The total page width is this offset plus the 
width set with the -w option. 

Do not print a warning message when an argument file cannot be opened. Failure to open a file 
still makes the exit status nonzero, however. 

Separate columns by the single character col umn-separator, default tab, instead of spaces. 

Do not print the 5-line header and the 5-linetrailer that are normally on each page, and do notfill 
out the bottoms of pages (with blank lines or form feeds). 

Print unprintable characters in octal backslash notation. 

Print version information on standard output then exit. 

Set the page width to page-wi dt h columns. The default is 72 . 


GNU Text Utilities 


ps 

ps— Report process status 

SYNOPSIS 

ps [-][lujsvmaxScewhrnu][txx] [0[ + |- ]k 1 [[ + ]-]k2 ...]] [pids] 
T here are also two long options: 

--sortX] + ]-]k ey[,[+]-]k ey[,...]] 


- -help 

M orelong options areon theway... 

DESCRIPTION 

ps gives a snapshot of the current processes. If you want a repetitive update of this status, use top. This man page documents 
the /proc-based version of ps, or tries to. 


COMMAND-LINE OPTIONS 


Command-linearguments may optionally be preceded by a butthereisno need for it. There are also some long options in 
GNU style; see the following subsection for those. 


1 

u 

i 

s 

V 

m 

f 

a 

x 

S 

c 

e 


Long format. 

U ser format: gives username and start time. 

Jobs format: pgid sid. 

Signal format, 
vm format. 

D isplays memory information (combinewith p flag to get number of pages). 
Forest family tree format for command line 
Show processes of other users too. 

Show processes without controlling terminal. 

Add child cpu time and page faults. 

Command name from task struct. 

Show environment after command line and +. 
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w Wideoutput: don't truncate command linestofiton oneline. 

h N o header, 

r Running procs only, 

n N umeric output for user and wchan. 

txx Only procs with controlling tty xx; use for xx the same letters as shown in then field. The 

tty name must be given immediately after the option, with no intervening space, for 
example, ps -tvi. 

0 [+!-]ki[,[+|-]k 2 [,...]] Order the process listing according to the multi level sort specified by the sequence of short 

keys from sort keys, k i , k 2 ,... . Default order specifications exist for each of the various 
formats of ps. T hese are overri dden by a user-specifi ed orderi ng. T he + is quite optional, 
merely reiterating the default direction on a key. - reverses direction only on the key it 
precedes. Aswith t and pids, theo option must be the last option in a single command 
argument, but specifications in successive arguments are catenated, 
pids List only the specified processes; they are comma-delimited. The list must be given 

immediately after the last option in a single command-line argument, with no intervening 
space, for example ps -ji , 4 , 5 . Lists specified in subsequent arguments are catenated, for 
example, ps - 11 , 23,4 5 6 will list all of the processes 1-6 in longformat. 

LONG COMMAND-LINE OPTIONS 

T hese options are preceded by a double hyphen. 

- -sortx[ + | - ] key[ , C hoose a multi letter key from the sortkeys section, x may be any convenient separator 

[ +1 -1 key [,...]] character. To beGN U-ish, use=. The+ is really optional because default direction is 

increasing numerical or lexicographic order. Example: 
ps -jax -sort=uid,-ppid,+pid 

--help Get a help message that summarizes the usage and gives a list of supported sort keys. This 

list may be more up-to-date than this man page. 

SORTKEYS 

N otethat the values used in sorting are the internal values ps uses and not the "cooked" values used in some of the output 
format fields. If someone wants to volunteer to write special comparison functions for the cooked values,...;-) 


Short 

Long 

D ezription 

C 

cmd 

Simple name of executable 

C 

cmdline 

Full command line 

f 

flags 

Flags as in longformat F field 

g 

pgrp 

Process group ID 

G 

tpgid 

Controlling tty process group ID 

j 

cutime 

Cumulative user time 

J 

cstime 

Cumulative system time 

k 

utime 

U ser ti me 

K 

stime 

System time 

m 

min_flt 

N umber of minor page faults 

M 

maj_flt 

N umber of major page faults 

n 

cminjflt 

C umulative minor page faults 

N 

cmaj_flt 

C umulative major page faults 

0 

session 

Session ID 

P 

pid 

Process ID 


continues 
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Short 

Long 

Description 

P 

ppid 

Parent process ID 

r 

rss 

Resident set size 

R 

resident 

Resident pages 

s 

size 

M emorysizein kilobytes 

S 

share 

Amount of shared pages 

t 

tty 

T he minor device number of tty 

T 

start_time 

T i m e process was started 

U 

uid 

User ID number 

u 

user 

Username 

V 

vsize 

T otal VM size in bytes 

y 

priority 

Kernel scheduling priority 

FIELD DESCRIPTIONS 



pri This isthe counter field in thetask struct. It isthetime in hz of theprocess's possibletimeslice 

ni Standard UN IX nice value; a positive value means less cpu time 

size Virtual i mage size; size of text+data+stack. 

rss Resident set size; kilobytes of program in memory. 

wchan N ame of the kernel function where the process is sleeping, with thesys stripped from the function name. If 
/boot/psdatabase does not exist, it isjust a hex number instead. 
stat Information about the status of the process. The first field is r for runnable s for sleeping, d for uninterruptible 
sleep, t for stopped or traced, or z for a zombie process. The second field contains w if the process has no resident 
pages. The third field is n if the process has a positive nice value (ni field). 
tt Controlling tty. 

pagein N umber of major page faults (page faults that cause pages to be read from disk, including pages read from the 
buffer cache). 

trs Text resident size. 

swap K i lobytes(or pages if -p isused) on swap device 

share Shared memory. 

UPDATING 

This proc-based ps works by reading the files in theproc filesystem, mounted on /proc.Thisps does not need to besuid 
kmem or haveany privilegesto run. Donotgivethis ps any special permisaons 

You will need to update the /boot/psdatabase fileby running /usr/sbm/psupdate to get meaningful information from the 
wchan field. This should be done every time you compileanew kernel. 

NOTES 

The member used math of task_struct is not shown, sinceerte.s checks to see if math is present. This causes the math flag 
to beset for all processes, and so it isworthless. 

Programs swapped out to disk will be shown without command-line arguments and unless thee option is given, in 
parentheses. 

%cpu shows the cputim^realti me percentage. It will not add up to 100 percent unless you are lucky. It is time used divided 
by the ti me the process has been runni ng. 

The size and rss fields don't count the page tables and the task struct of a proc; this is at least 12k of memory that is 
always resident, size isthe virtual size of theproc (code+data+stack). 
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BUGS 

tty names are hard-coded: virtual consoles are v 1 , v 2 ; serial lines ares o and si; pty's are p po, ppi ... pqo, pqi,.... 

AUTHORS 

ps was originally written by Branko Lankester (iankeste@twi.uva.ni) M ichael K. Johnson (johnsonm@sunsite.unc.edu) 
rewrote it significantly to usetheproc filesystem, changing a few things in the process. M ichael Shields 
(mjshieid@nyx.cs.du.edu) added the multiple-pids feature. C harles Blake(cbiake@ucsd.edu) added multilevel sorting and is 
the current mai ntai ner of the proc -ps suite 

Cohesive Systems 27 July 1994 


psbb 

psbb— Extract bounding box from PostScript document 

SYNOPSIS 

psbb file 

DESCRIPTION 

psbb reads fi i e, which should be a PostScript document conforming to the document structuring conventions and looks for 
a %%BoundingBox comment. If it finds one, it prints a line 

llx lly urx ury 

on the standard output and exits with zero status. If it doesn't find such a line or if the line is invalid, it prints a message and 
exits with nonzero status. 

SEE ALSO 

grops(l) 

Groff Version 1.09, 6 August 1992 


psidtopgm 

psidtopgm— Convert PostScript image data into a portable graymap 

SYNOPSIS 

psidtopgm width height bits/sample [imagedat a] 

DESCRIPTION 

psidtopgm reads the image data from a PostScript file as input and produces a portable graymap as output. 

This is a very simple and limited program, and is here only because so many people have asked for it. T o use it you have to 
manually extract the readhexstring data portion from your PostScript file, and then givethewidth, height, and bit^sample 
on the command line. Before you attempt this, you should at least read the description of the image operator in the PostScript 
Language Reference M anual. 

It would probably not be too hard to write a script that uses this filter to read a specific variety of PostScript image, but the 
variation is too great to make a general-purpose reader. Unless, of course, you want to write a full-fledged PostScript 
interpreter... 

SEE ALSO 

pnmtops(l), pgm(5) 
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AUTHOR 

Copyright© 1989 byjef Poskanzer. 


2 August 1989 


pstopnm 

pstopnm— C onvert a PostScript file into a portable anymap 

SYNOPSIS 

pstopnm [-forceplain][-help][-llx s][-lly s][-landscape][-portrait][-nocrop] 
[-pbm ]-pgm ]-ppm][-urx s][-ury s][-verbose][-xborder n][-xmax n][-xsize f] 
[-yborder f ][-ymax n][-ysize n] psflie[.ps] 


DESCRIPTION 

pstopnm reads a PostScript file as input and produces portable anymap files as output. Thisprogram isjust a useful shell script 
that runs G hostScript to render a PostScript into one or morepnm files, pstopnm will create as many files as the number of 
pagesin the PostScript document. If the input file is named psfiie.ps, the name of thefiles will bepsfiieooi .ppm, 
psfiie 002 .ppm, and so on. 

The program maps a rectangular portion of the PostScript document into an image file according to the command-line 
options. T he selected area will always be centered in the output file, and may have borders around it. T he image area to be 
extracted from the PostScript file and rendered into a portable anymap is defined by four numbers, the lower-left corner and 
the upper-right corner x and y coordinates. These coordinates are usually specified by theBoundingBox comment in the 
PostScript file header, but they can be overridden by the user by specifying one or more of the following flags: -iix, -iiy, 
-urx, and -ury. T he presence and thickness of a border to be left around the i mage area is controlled by the use of the flags 
-xborder and -yborder. If BoundingBox parameters are not found, and image area coordinates are not specified on the 
command line, default values are used. Unless both output file width and height are specified via the-xsize and -ysize 
flags, the program will map the document into the output image by preserving its aspect ratio. 


OPTIONS 

-forceplain 

-help 

-llx bx 

-lly by 

-landscape 

-portrait 

-nocrop 

-pbm -pgm -ppm 
-urx t x 
-ury ty 
-verbose 
-xborder f r ac 

-xmax xs 
-xsize xs 
-yborder f r ac 

-ymax ys 
-ysize ys 


Forces the output file to bea plain (in other words, not "raw") portable anymap. 

Prints the command syntax. 

Selects bx as the lower left corner x coordinate (in inches). 

Selects by asthe lower left corner y coordinate (in inches). 

Renders the image in landscape mode. 

Renders the image in portrait mode. 

Does not crop the output image dimensions to match the PostScript image area dimensions. 

Selects the format of the output fi le. By default, all files are rendered as portable pixmaps (ppm format). 
Selects t x asthe upper-right corner x coordinate (in inches). 

Selects t y asthe upper-right corner y coordinate (in inches). 

Prints processing information to stdout. 

Specifies that theborder width alongtheY axisshould be f r a c times the document width as specified by 
the bounding box comment in the PostScript file header. The default value i so. i. 

Specifies that the maxi mum output image width should have a size less or equal to xs pixels (default: 612 ). 
Specifies that the output imagewidth must beexactlyxs pixels. 

Specifies that theborder width alongtheX axisshould be f r a c times the document width as specified by 
the bounding box comment in the PostScript file header. The default value i so. 1 . 

Specifies that the maxi mum output image height should have a size less or equal toys pixels (default: 792 ). 
Specifies that the output image height must be exactly ys pixels. 
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BUGS 

The program will produce incorrect results with PostScript filesthat initialize the current transformation matrix. In these 
cases, page translation and rotation will not have any effect. T o render these files, probably the best bet is to use the following 
flags: 

pstopnm -xborder 0 -yborder 0 -portrait -nocrop file.ps 

Additional flags may be needed if the document is supposed to be rendered on a medium different from letter-size paper. 

SEE ALSO 

gs(l), pstofits(l) 

COPYRIGHT 

Copyright© 1992 Smithsonian Astrophysical Observatory. PostScript is a trademark of Adobe Systems Inc. 

AUTHOR 

Alberto Accomazzi, WI PL, Center for Astrophysics 

28 December 1992 


pstree 

pstree— D isplay a tree of processes 

SYNOPSIS 

pstree [-a][-c][-h][-1][-p][-u][pi d|user ] 

DESCRIPTION 

pstree shows running processes as a tree. The tree is rooted at either pid or init if pid is omitted. If a username is specified, 
all process trees rooted at processes owned by that user are shown. 

pstree visually merges identical branches by putting them in square brackets and prefixing them with the repetition count; 
for example, 

init-+-getty 
I-getty 
I-getty 
'-getty 


becomes 

init--4*[getty] 


OPTIONS 

-a Show command-line arguments. Ifthecommand line of a process is swapped out, that process is shown in 
parentheses, -a implicitly disables compaction. 

-c D isable compaction of identical subtrees. By default, subtrees are compacted whenever possible. 

-h H ighlight the current process and its ancestors. This is a no-op if the terminal doesn't support highlighting or if 

neither the current process nor any of its ancestors are in the subtree being shown. 

-l D isplay long lines. By default, lines are truncated to the display width or 132 if output is sent to a non-tty or if 
the display width isunknown. 

-p Show pids. pidsare shown as decimal numbersin parentheses after each process name, -p implicitly disables 
compaction. 

-u Show uid transitions. Whena/er the uid of a process differs from theuid of its parent, the new uid is shown in 
parentheses after the process name. 
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FILES 

/proc Location of theprocfilesystem 

AUTHOR 

Werner Almesberger (aimesben@di.epfi.ch) 

SEE ALSO 

ps(l), top(l) 

Linux, 11 October 1994 


psupdate 

psupdate — U pdate the ps database of kernel offsets 

SYNOPSIS 

psupdate [system path] 

DESCRIPTION 

psupdate updates the /boot/psdatabase fileto correspond to the current kernel image system mapfile, /usr/src/iinux/vmiinux 
by default. 

OPTIONS 

If your system mapfile is not /usr/src/iinux/vmiinux, you may give the name of an alternate mapfile on the command line. 

FILES 

/boot/psdatabase 

/usr/src/linux/vmlin 

SEE ALSO 

ps( 1), top(l), utmp(5) 

AUTHORS 

Original code written by Branko Lankaster, horribly munged by M ichael K. Johnson in a desperate effort to add /etc/ 
psdatabase support to procps. Someday, it should be rewritten, and the support in ps for alternate namelists added. Anyone 
want to volunteer to be added to the "Authors" section? 

Cohesive Systems 15 September 1993 


qrttoppm 

qrttoppm — C onvert output from the Q RT ray tracer i nto a portable pixmap 

SYNOPSIS 

qrttoppm [ q r t fiI e ] 

DESCRIPTION 

qrttoppm readsaQRT file as input and produces a portable pixmap as output. 
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SEE ALSO 

ppm(5) 

AUTHOR 

Copyright® 1989 byjef Poskanzer. 


25 August 1989 


quota 

quota— D isplay disk usage and limits 

SYNOPSIS 

quota [ -guv | q ] 
quota [ -uv | q ] user 
quota [ -gv | q ] group 

DESCRIPTION 

quota displays users' disk usage and limits By default, only the user quotas are printed. 

-g Print group quotas for the group of which the user is a member. T he optional -u flag is equivalent to the default, 

-v Will display quotas on filesystems where no storage is allocated. 

-q Print a moreterse message, containing only information on filesystemswhereusageisover quota. 

Specifying both -g and -u displays both the user quotas and the group quotas (for the user). 

0 nly the superuser may use the -u flag and theoptional user argument to view thelimits of otherusers. N on-superusers can 
use the -g flag and optional group argument to view only the limits of groups of which they are members. 

The-q flag takes precedence over the -v flag. 

quota reports the quotas of all the filesystems listed in /etc/fstab. For filesystems that areN FS-mounted, a call to the 
rpc.rquotad on the server machine is performed to get the information. If quota exits with a nonzero status, one or more 
fi lesystems are over quota. 

FILES 

quota.user Located at the filesystem root with user quotas 

quota.group Located at the filesystem root with group quotas 

/etc/fstab T o find filesystem names and locations 

SEE ALSO 

quotactl(2), fstab(5), edquota(8), quotacheck(8), quotaon(8), repquota(8) 

8 January 1993 


ranlib 

ranlib— Generate index to archive 

SYNOPSIS 

ranlib [ -vj-V] archive 
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DESCRIPTION 

raniib generates an index to the contents of an archive and stores it in the archive. The index lists each symbol defined by a 
member of an archive that is a relocatable object file. 

Y OU may use nm -s or nm - - print -armap to I ist this index. 

An archive with such an index speeds up linking to the library, and allows routines in the library to call each other without 
regard to their placement in the archive. 

The GNU raniib program is another form of G N U ar; running raniib is completely equivalent to executing ar -s. 

OPTIONS 

-v Print the version number of raniib and exit 



SEE ALSO 

binutiis entry in into; TheGNU BinaryU tilities, Roland H . Pesch (October 1991); ar(i); nm(i). 

COPYING 

Copyright© 1991 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this 
manual provided the copyright notice and this permission notice are preserved on all copies. 

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions 
for modified versions, except that this permission notice may be included in translations approved by the Free Software 
Foundation instead of in the original English. 

Cygn us support, 5 N ovember!991 
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rasttopnm— C onvert a Sun raster file into a portable anymap 

SYNOPSIS 

rasttopnm [rastfiI e ] 

DESCRIPTION 

rasttopnm reads a Sun raster file as input and produces a portable anymap as output. The type of the output file depends on 
the input file— if it's black and white, apbm file is written; else if it's grayscale a pgm file; else a ppm file. The program tel Is you 
which type it is writing. 

SEE ALSO 

pnmtorast(l), pnm(5) 

AUTHOR 

Copyright© 1989,1991 byJefPodranzer. 

13 January 1991 
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rawtopgm 

rawtopgm— Convert raw grayscale bytes into a portablegraymap 

SYNOPSIS 

rawtopgm [-headerskip N][-rowskip N][-tb|-topbottom][wi dth hei ght ][i magedata] 

DESCRIPTION 

rawtopgm reads raw grayscale bytes as i nput and produces a portable graymap as output. T he input file is just grayscale bytes. 

If you don't specify the width and height on the command line the program will check the size of the image and try to make 
a quadratic image of it. It is an error to supply a non-quadratic image without specifying width and height. The maxvai is 
assumed to be 255. 

OPTIONS 

-headerskip If thefile has a header, you can usethisflag to skip over it. 

-rowskip If there is padding at the ends of the rows, you can skip it with thisflag. N otethat rowskip can be a real 

number. Amazingly, I once had an image with 0.376 bytes of padding per row. Thisturned out to be due 
to a file transfer problem, but I was still able to read the image. 

-tb -topbottom Flips the image upside down. The first pixel in a pgm file is in the lower-left corner of the image. For 

conversion from images with the first pixel in the upper-left corner (for example theM olecular Dynamics 
and Leica confocal formats), this flips the i mage right. T his is equivalent to rawtopgm [tile] | pnmtiip 

-tb. 


BUGS 

If you don't specify the image width and height, the program will try to read the entire image to a memory buffer. If you get 
a message that states that you are out of memory, try to specify the width and height on the command line. Also, the -tb 
option consumes much memory. 

SEE ALSO 

pgm(5), rawtoppm(l), pnmflip(l) 

AUTHORS 

Copyright® 1989 byjef Poskanzer; modified June 1993 by Oliver Trepte (oiiver@fysik4.kth.se). 

15Junel993 


rawtoppm 

rawtoppm— C onvert raw RG B bytes into a portable pixmap 

SYNOPSIS 

rawtoppm[-headerskip N][-rowskip N][-rgbj-rbgj-grb }-gbrJ-brg|-bgr ] 

[-interpixel!-interrow] width height [i magedata] 

DESCRIPTION 

rawtoppm reads raw RGB bytes as input and produces a portable pixmap as output. The input file is just RGB bytes. You have 
to specify the width and height on the command line because the program obviously can't get them from thefile. The maxvai 
is assumed to be 255. If the resulting image is upside down, run it through pnmfiip -tb. 
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OPTIONS 

-headerskip If the file has a header, you can usethisflag to skip over it. 

-rowskip If there is padding at the ends of the rows, you can skip it with thisflag. 

-rgb -rbg -grb -gbr -brg -bgr T hese flags let you specify alternate color orders. T he default is -rgb. 

-interpixei -interrow T hese flags let you specify how the colors are interleaved. The default is -interpixei, 

meaning interleaved by pixel. A byte of red, a byte of green, and a byte of blue, or whatever 
color order you specified, -interrow means interleaved by row— a row of red, a row of 
green, a row of blue, assuming standard RG B color order. An -interpiane flag— all the red 
pixels, then all the green, then all the blue—would bean obvious extension, but is not 
implemented. You could get the same effect by splitting thefile into three parts (perhaps 
using dd), turning each part into a PGM file with rawtopgm, and then combining them with 

rgb3toppm. 


SEE ALSO 

ppm(5), rawtopgm(l), rgb3toppm(l), pnmflip(l) 

AUTHOR 

Copyright© 1991 byjef Poskanzer. 

6 February 1991 


rep 

rep— Remote file copy 

SYNOPSIS 

rep [ - px] [-k realm] filel fiI e 2 

rep [-px] [-r] [-k Ar realm] file ... directory 

DESCRIPTION 

rep copies files between machines. Each file or directory argument is either a remote filename of the form rname@rhost:path, 
or a local filename (containing no : characters, or a / before any : characters). 

-r If any of thesourcefilesaredirectories, rep copies each subtree rooted at that name; in this case the destination 

must be a directory. 

-p Causes rep to attempt to preserve (duplicate) in its copies the modification times and modes of the source files, 
ignoring the umask . By default, the mode and owner of f i i e2 are preserved if it already existed; otherwise, the 
mode of the source file modified by the umask 2 on the destination host is used. 

-k Requests rep to obtain tickets for the remote host in realm realm instead of the remote host's realm as determined 
by krb_realmofhost 3. 

-x T urns on DES encryption for all data passed by rep. This may impact response time and CPU utilization, but 
provides increased security. 

If path is not a full pathname it is interpreted relative to the login directory of the specified user ruser on rhost, or your 
current username if no other remote username isspecified. A path on a remote host may be quoted (using \,", or') so that 
the meta characters are i nterpreted remotely. 

rep does not prompt for passwords; it performs remote execution via rsh(l), and requires the same authorization, 
rep handles third-party copies, where neither source nor target files are on the current machine. 
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SEE ALSO 

cp(l), ftp(l), rsh(l), rlogin(l) 

HISTORY 

The rep command appeared in BSD 4.2 . The version of rep described here has been reimplemented with Kerberos in BSD 
4.3 Reno. 

BUGS 

Doesn't detect all cases in which the target of a copy might be a file when only a directory should be legal. 

Is confused by any output generated by commands in a or file on the remote host. 

The destination usernameand hostname may have to be specified asrhost.rname when the destination machine is running 
the BSD 4.2 version of rep. 

BSD 4.3r, 27July 1991 

rcs 

res— C hange RC S fi le attributes 

SYNOPSIS 

res options file ... 

DESCRIPTION 

res creates new RCS files or changes attributes of existing ones. An RCS file contains multiple revisions of text, an access list, 
a change log, descriptive text, and some control attributes. For res to work, the caller's login name must be on the access 
list—unless the access list is empty, the caller is the owner of the file or the superuser, or the-i option is present. 

Pathnames matching an RCS suffix denote RCS files; all others denote working files. N ames are paired as explained in ci(l). 
Revision numbersusethesyntax described in ci(l). 

OPTIONS 

-i Create and initialize a new RCSfile, but do not deposit any revision. If the RCS file has no path prefix, try 

to place it first into the subdirectory ./ rcs, and then into the current directory. If the RCS file already 
exists, print an error message. 

-ai ogi ns Append the login namesappearing in the comma-separated list i ogi ns to the access list of the RCS file. 

-Aoidfiie Append the access list of oi df i i e to the access list of the RCS file. 

-e[i ogi ns ] E rase the logi n names appeari ng i n the comma-separated list i ogi ns from the access list of the RCS file. If 

i ogi ns isomitted, erase the entire access list. 

-b [ r e v ] Set the default branch to r ev .If rev isomitted, the default branch is reset to the (dynamically) highest 

branch on the trunk. 

-cst ring Set the comment leader to s t r i ng . An initial ci,or an rcs -i without -c, guesses the comment leader from 

the suffix of the working fi lename. 

This option is obsolescent, since RCS normally uses the precedi ng$Log$ line's prefix when inserting log lines during 
checkout (see co(l)). H owever, older versions of RCS use the comment leader instead of the$Log$ line's prefix, so if you plan 
to access a file with both old and new versions of RCS, make sure its comment leader matches its$Log$ line prefix. 

-ksubst Set the default keyword substitution to subst . The effect of keyword substitution is described in co(l). 

Giving an explicit -k option to co, resdiff, and resmerge overridesthisdefault. Beware rcs -kv, because 
-kv is incompatible with co -l. Use rcs -kkv to restore the normal default keyword substitution. 
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-1 [rev] 

-u[r e v ] 


-L 

-U 

-mr e v: msg 
-M 

-nname [: [r ev ] 


-Nn a me [: [r e v 
-orange 


-q 

-I 

-sst at e [lr ev ] 


-t[f i I e ] 


-t-st ring 
-T 


-V 

-Vn 

-xsuf f i xes 
-zzone 


Lock the revision with number rev. If a branch isgiven, lock the latest revision on that branch. If rev is 
omitted, lock the latest revision on the default branch. Locking prevents overlapping changes. If someone 
else already holds the lock, the lock is broken as with res -u. 

Unlock the revision with number rev. If a branch isgiven, unlock the latest revision on that branch. If rev 
is omitted, remove the latest lock held by the caller. N ormally, only the locker of a revision can unlock it. 
Somebody else unlocking a revision breaks the lock. This causes a mail message to be sent to the original 
locker. The message contains a commentary solicited from the breaker. The commentary isterminated by 
end-of-fileor by a line containing a period by itself. 

Set locking to strict, strict locking meansthat the owner of an RC S file is not exempt from locking for 
checkin. This option should be used forfilesthat are shared. 

Set locking to non-strict. non-strict locking meansthat the owner of a file need not lock a revision for 
checkin. This option should not be used for files that are shared. Whether default locking isstrict is 
determined by your system administrator, but it is normally strict. 

Replace revision r ev 's log message with msg. 

Do not send mail when breaking somebody else's lock. This option is not meant for casual use; it is meant 
for programs that warn users by other means, and invoke res -u only as a low-level lock-breaking 
operation. 

] Associate the symbolic name name with the branch or revision rev. Delete the symbolic name if both : and 

rev areomitted; otherwise, print an error message if name is already associated with another number. If r ev 
is symbolic, it is expanded before association. A rev consisting of a branch number followed by a period 
stands for the current latest revision in the branch. A : with an empty rev stands for the current latest 
revision on the default branch, normally thetrunk. For example, res -nname: rcs/* associates name with 
the current latest revision of all the named RCS files; this contrasts with rcs -nname :$ rcs/*, which 
associates name with the revision numbers extracted from keyword strings in the corresponding working 
files. 

Act I ike-n, except override any previous assignment of name. 

Deletes ("outdates") the revisions given by range. A range consisting of a single revision number means 
that revision. A range consisting of a branch number means the latest revision on that branch. A range of 
theform revi: rev 2 means revisionsr evi to r e v 2 on the same branch, : r ev meansfrom the beginning of 
the branch containing rev up to and including rev, and rev : meansfrom revision rev to theend of the 
branch containing rev. N one of the outdated revisionscan have branches or locks 
Run quietly; do not print diagnostics. 

Run interactively, even if the standard input is not a terminal. 

Set the state attribute of the revision r ev tostate. If r ev isabranch number, assume the latest revision on 
that branch. If rev isomitted, assume the latest revision on the default branch. Any identifier is acceptable 
for state. A useful set of states is Exp (for experimental), stab (for stable), and Rei (for released). By 
default, ci(l) sets the state of a revision to Exp. 

Write descriptive text from the contents of the named f i 1 e into the RCS file, deleting the existing text. 

T he f i 1 e path name can not begin with -. If f i 1 e isomitted, obtain the text from standard input, 
terminated by end-of-fileor by a line containing a period by itself. Prompt for thetext if interaction is 
possible; see - 1 . With -i, descriptive text is obtained even if -t isnot given. 

Write descriptive text from thes t ring into the RCS file, deleting the existing text. 

Preserve the modification time on the RCS file unless a revision is removed. This option can suppress 
extensive recompilation caused by a make(l) dependency of some copy of theworkingfileon the RCS file. 
Use this option with care; it can suppress recompilation even when it is needed, that is when a change to 
the RCS file would mean a change to keyword strings in the working file. 

Print RCS's version number. 

EmulateRCSversion n. Seeco(l) for details 

Usesuf f i *es to characterize RCS files. Seeci(l) for details. 

Usezone as the default time zone. This option has no effect; it is present for compatibility with other RCS 
commands. 
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At least oneexplicitoption must be given, to ensure compatibility with future planned extensionsto thercs command. 

COMPATIBILITY 

The-brev option generates an RCS file that cannot be parsed by RCSversion 3 or earlier. 

The-ksubst options (except -kkv) generate an RCS file that cannot be parsed by RCSversion 4 or earlier. 

Use res -vn to makean RCS file acceptable to RCSversion n by discarding information that would confuse version n. 
RCSversion 5.5 and earlier does not support the -x option, and requires a ,v suffix on an RCS pathname. 

FILES 

res accesses files much asci(l) does, except that it uses the effective user for all accesses, it does not write the working file or 
its directory, and it does not even read the working file unless a revision number of $ is specified. 

ENVIRONMENT 

RcsiNiTt i [: r ev ] 0 ptions prepended to the argument list, separated by spaces. Seeci(l) for details. 

DIAGNOSTICS 

The RCS pathname and the revisions outdated are written to the diagnostic output. The exit status is zero if and only if all 
operati ons were successfuI. 

IDENTIFICATION 

Author: Walter F. Tichy. 

M anual Page Revision: 5.13; Release D ate: 1995/06/05. 

Copyright 1982,1988,1989 Walter F. Tichy. 

Copyright 1990,1991,1992,1993,1994,1995 Paul Eggert. 

SEE ALSO 

rcsintro(l), co( 1), ci(l), ident(l), rcsclean(l), rcsdiff(l), rcsmerge(l), rlog(l), rcsfile(5) 

"RCS—A System forVersion Control’' by Walter F. Tichy, software Practice & Experience 15, 7 (July 1985), pages 
637-654. 

BUGS 

A catastrophe (for example, a system crash) can cause RCS to leave behind a semaphore file that causes later invocations of 
RCS to claim that the RCS file is in use. T o fix this, remove the semaphore file. A semaphore file's name typically begins 
with a comma or ends with an underscore 

The separator for revision ranges in the-o option used to be - instead of:, but this leads to confusion when symbolic names 
contain -. For backwards compatibility, res -o still supports the old - separator, but it warns about this obsolete use. 

Symbolic names need not refer to existing revisions or branches. For example, the-o option does not remove symbolic names 
for the outdated revisions; you must use -n to remove the names. 

GNU, 5Junel995 


rcsclean 

rcsciean— C lean up working files 

SYNOPSIS 

rcsclean [options ] [fiIe ...] 
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DESCRIPTION 

rcsciean removes files that are not being worked on. rcsciean -u also unlocks and removes files that are bei ng worked on 
but have not changed. 

For each fi i e given, rcsciean compares the working file and a revision in the corresponding RC S file. If it finds a difference, 
it does nothing. Otherwise, it first unlocks the revision if the -u option isgiven, and then removes theworkingfileunless the 
working file iswritableand the revision islocked. It logs its actions by outputting the corresponding res -u and ™ -t 
commands on the standard output. 

Files are paired as explained in ci( 1). If no f i i e isgiven, all working files in the current directory are cleaned. Pathnames 
matching an RC S suffix denote RC S files; all others denote working files. 

The number of the revision to which the working file is compared may be attached to any of the options -n, -q, -r, or-u. If 
no revision number is specified, then if the -u option isgiven and the caller hasonerevision locked, rcsciean uses that 
revision; otherwise, rcsciean uses the latest revision on the default branch, normally the root. 

rcsciean is useful for clean targets in makefiles. See also rcsdiff(l), which prints out the differences, and ci(l), which 
normally reverts to the previous revision if a file was not changed. 

OPTIONS 

-ksubst Usesubst -style keyword substitution when retrieving the revision for comparison. Seeco(l) for details. 

-n [ r e v ] Do not actually remove any files or unlock any revisions. Using this option will tell you what rcsciean 

would do without actually doing it. 

-q[ra/] Do not log the actionstaken on standard output. 

-r [rev] This option has no effect other than specifying the revision for comparison. 

-t Preserve the modification time on the RCS file a/en if the RC 5 file changes because a lock is removed. 

Thisoption can suppress extensive recompilation caused by a make(l) dependency of some other copy of 
the working file on the RCS file. Use this option with care; it can suppress recompilation even when it is 
needed, that is, when thelock removal would mean achangeto keyword strings in theother working file, 
-u [ r e v ] Unlock the revision if it islocked and no difference is found. 

-v Print RCS'sversion number. 

-vn Emulate RCS version n. See co(l) for details. 

-xsuffixes Usesuffixes to characterize RC S files. See c±(l) for details. 

-zzone U se zone asthetimezonefor keyword substitution; seeco(l) for details. 

EXAMPLES 

rcsciean *.c *.h removes all worki ng files ending i n .c or.h that were not changed sincetheir checkout, 
rcsciean removes all working files in the current directory that were not changed sincetheir check-out. 

FILES 

rcsciean accesses fi les much asci(l) does. 

ENVIRONMENT 

rcsinit 0 ptions prepended to the argument list, separated by spaces. A backslash escapes spaces within an option. T he 
rcsinit options are prepended to the argument lists of most res commands. U seful rcsinit optionsindude-q, 
-v, -x, and -z. 

DIAGNOSTICS 

The exit status is zero if and only if all operations were successful. M issing working files and RCS files are silently ignored. 
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IDENTIFICATION 

Author: Walter F. Tichy. 

M anual Page Revision: 1.12; Release D ate: 1993/11/03. 

Copyright© 1982,1988,1989 Walter F. Tichy. 

Copyright© 1990,1991,1992,1993 Paul Eggert. 

SEE ALSO 

ci(l), co(l), ident(l), ncs(l), rcsdiff(l), rcsintro(l), rcsmerge(l), rlog(l), rcsfile( 5 ) 

"RCS—A System forVersion Control'' by Walter F. Tichy, software Practice & Experience 15, 7 (July 1985), pages 
637-654. 

BUGS 

At least onef i i e must be given in older U NIX versionsthat do not provide the needed directory scanning operations. 

GNU,3 November 1993 


rcsdiff 

rcsdiff — C ompare res revisions 

SYNOPSIS 

rcsdiff [ -ksubst ][-q ] [-rr e v 1 [ -rr e v 2 ]][-T ] [ —V [ n ] ] [ —xs u f f i x e s ] [-zz one ] 

[di f f options ] f i I e . . . 

DESCRIPTION 

rcsdiff runs diff(l) to compare two revisions of each RCSfilegiven. 

Pathnames matching an rcs suffix denote RCS files; all others denote working files. N ames are paired as explained in ci(l). 

The option -q suppresses diagnostic output. Zero, one, or two revisions may be specified with -r. The option -ksubst affects 
keyword substitution when extracting revisions, as described in co(l); for example, -kk -ri.i -ri .2 ignores differences in 
keyword values when comparing revisions 1.1 and 1.2. T 0 avoid excess output from locker name substitution, -kkvi is 
assumed if at most one revision option is given, no -k option is given, -kkv isthe default keyword substitution, and the 
working file's mode would be produced by co -1. Seeco(l) for details about -t, -v, -x, and -z. Otherwise, all options of 
diff(l) that apply to regular files are accepted, with the same meaning as for diff. 

If both r e v 1 and re»2 are omitted, rcsdiff compares the latest revision on the default branch (by default the trunk) with the 
contents of the corresponding working file. This is useful for determining what you changed si nee the last checkin. 

If revi is given, but r ev2 is omitted, rcsdiff compares revision revi of the RCS file with the contents of the corresponding 
working file. 

If both revi and re»2 are given, rcsdiff compares revisions revi and r ev2 of the RCS file. 

Both revi andrev2 may be given numerically or symbolically. 

EXAMPLE 

The command 
rcsdiff f.c 

compares the latest revision on the default branch of the RCS file to the contents of the working file f.c. 

ENVIRONMENT 

rcsinit Options prepended to the argument list, separated by spaces. Seeci(l) for details. 
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DIAGNOSTICS 

Exit status iso for no differences during any comparison, i for some differences, 2 for trouble. 

IDENTIFICATION 

Author: Walter F. Tichy. 

M anual Page Revision: 5.5; Release D ate: 1993/11/03. 

Copyright© 1982,1988,1989 Walter F. Tichy. 

Copyright© 1990,1991,1992,1993 Paul Eggert. 

SEE ALSO 

ci(l), co(l), diff(l), ident(l), rcs(l), rcsintro(l), rcsmerge(l), rlog(l) 

"RCS—A System forVersion Control'' by Walter F. Tichy, software Practice & Experience 15, 7 (July 1985), pages 
637-654. 

GNU,3 November 1993 
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resfreeze— Freeze a configuration of sources checked in under RCS 

SYNOPSIS 

resfreeze [name] 

DESCRIPTION 

resfreeze assigns a symbolic revision number to a set of RCS files that form a valid configuration. 

Theidea isto run resfreeze each timea new version is checked in. A unique symbolic narne(c_number, where number is 
increased each time resfreeze is run) is then assigned to the most recent revision of each RCS file of the main trunk. 

An optional name argument to resfreeze gives a symbolic name to the configuration. The unique identifier isstill generated 
and is listed in the log file, but it will not appear as part of the symbolic revision name in the actual RCS files. 

A log message isrequested from the user for future reference. 

The shell script works only on all RCS files at onetime. All changed files must be checked in already. Run rcsciean(l) first 
and see whether any sources remain in the current directory. 

FILES 

rcs/. resfreeze.ver Version number 

rcs/. resfreeze.log Logmessages, most recent first 

AUTHOR 

Stephan V. Bechtolsheim 

SEE ALSO 

co(l), rcs(l), rcsclean(l), rlog(l) 

BUGS 

resfreeze does not check whether any sources are checked out and modified. 

Although both sourcefilenamesand RCS filenames are accepted, they are not paired as usual with res commands. 

Error checking is rudimentary. 
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rcsfreeze isjust an optional example shell script, and should not betaken too seriously. Seecvs for a more complete 
solution. 

GNU, 3 November 1990 


rcsintro 

rcsintro— Introduction to res commands 

DESCRIPTION 

The Revision Control System (RCS) manages multiple revisions of files. RCS automates the storing, retrieval, logging, 
identification, and merging of revisions. RCS is useful for text that is revised frequently; for example programs, documenta¬ 
tion, graphics, papers, and form letters. 

The basic user interface is extremely simple. The novice only needs to learn two commands: ci(l) and co(l). ci, short for 
check in, deposits the contents of a file into an archival file called an RCS file. An RCS file contains all revisions of a 
particular file, co, short for check out, retrieves revisions from an RCS file. 

FUNCTIONSOF RCS 

Store and retrieve multiple revisions of text. RCSsavesall old revisions in a space-efficient way. Changes no longer destroy 
theoriginal because the previous revisions remain accessible. Revisionscan be retrieved according to ranges of revision 
numbers, symbolic names, dates, authors, and states. 

Maintain a complete history of changes. RCS logs all changes automatically. Besides the text of each revision, RCS stores 
the author, the date and time of checkin, and a log message summarizing the change. The logging makes it easy to find out 
what happened to a module without having to compare source listings or having to track down colleagues. 

Resolve access conflicts W hen two or more programmers wish to modify the same revision, RCS alerts the programmers 
and preventsonemodification from corrupting the other. 

Maintain a tree of revisions RCS can maintain separate lines of development for each module. It stores a tree structure that 
represents the ancestral relationships among revisions. 

Merge revisions and resolve conflicts T wo separate lines of development of a module can be coalesced by merging. If the 
revisions to be merged affect the same sections of code, RCS alerts the user about the overlapping changes. 

Control releases and configurations Revisionscan be assigned symbolic names and marked as released, stable, experimen¬ 
tal, and so on. With these facilities, configurations of modules can be described simply and directly. 

Automatically identify each revision with name, revision number, creation time, author, and so on. T he identification 
is like a stamp that can be embedded at an appropriate place in the text of a revision. The identification makes it simple to 
determinewhich revisions of which modules make up a given configuration. 

M inimize secondary storage. RCS needs little extra space for the revisions (only the differences). If intermediate revisions 
are deleted, the corresponding deltas are compressed accordingly. 

GETTING STARTED WITH RCS 

Suppose you have a file f .c that you wish to put under control of RCS. Ifyou have not already done so, make an rcs 
directory with the command: 

mkdir RCS 

Then invoke the check in command: 
ci f.c 

Thiscommand creates an RCSfilein theRcs directory, storest.c into it as revision 1.1, and deletest.c. It also asks you for 
a description. The description should be a synopsis of the contents of the file. All later check in commands will ask you fora 
log entry, which should summarize the changes that you made. 




Parti: User Commands 


Files in theRcs directory are called RCS files; the others are cal led working files. To get back the working filef .c in the 
previous example, use the check out command: 

CO f.c 

This command extracts the latest revision from theRCS file and writes it into f.c. If you want to edit f.c, you must lock it 
as you check itoutwith thecommand: 

CO -1 f.c 

You can now edit f.c. 

Suppose after some editing you want to know what changes that you have made. Thecommand: 
rcsdiff f.c 

tel Is you the difference between the most recently checked-in version and the working file. You can check the file back in by 

invoking 

ci f.c 

This increments the revision number properly. 

If ci complains with the message: 
ci error: no lock set by your name 

then you have tried to check in afilea/en though you did not lock it when you checked it out. Of course it is too late now 
to do the checkout with locking, because another checkout would overwrite your modifications. Instead, invoke 
res -1 f.c 

This command will lock the latest revision for you, unless somebody else got ahead of you already. In that case, you'll have to 
negotiate with that person. 

Locking assures that you, and only you, can check in the next update, and avoids nasty problems if several people work on 
the same file. Even if a revision is locked, it can still be checked out for reading, compiling, and so on. All that locking 
prevents is a check-in by anybody but the locker. 

If your RCS file is private— if you are the only person who is going to deposit revisions into it— strict locking is not needed 
and you can turn it off. If strict locking is turned off, the owner of the RCS file need not have a lock for checkin; all others 
still do. Turning strict locking off and on is done with the commands res -u f.c and res -l f.c. If you don't want to 
clutter your working directory with RCSfiles, create a subdirectory called rcs in your working directory, and move all your 
RCS files there, rcs commands will look first into that directory to find needed files. All the commands discussed here will 
still work, without any modification. (Actually, pairs of RCS and working files can be specified in three ways: both are given, 
only the working fi le is given, or only the RC S file is given. Both RC S and working files may have arbitrary path prefixes; rcs 
commands pair them up intelligently.) 

T o avoid the deletion of the working file during checkin (in case you want to continue editing or compiling), invoke 
ci -1 f.c or ci -u f.c 

These commands check inf.c as usual, but perform an implicit checkout. T hefirst form also locks the checked in revision, 
the second one doesn't. Thus, these options save you one checkout operation. The first form is useful if you want to 
continue editing, thesecond one if you just want to read thefile. Both update the identification markersin your working 
file. (See the following subsection, "Automatic Identification.’') 

You can giveci the number you want assigned to a checked in revision. Assume all your revisions were numbered 1.1,1.2, 
1.3, etc., and you would like to start release 2. Thecommand: 
ci -r2 f.c or ci -r2.1 f.c 


assigns the number 2.1 to the new revision. From then on, ci will number thesubsequent revisions with 2.2, 2.3, and so on. 
The corresponding co commands: 
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co -r2 f.c 
and 

co -r2.1 f.c 

retrieve the latest revision numbered 2.x and the revision 2.1, respectively, co without a revision number selects the latest 
revision on thetrunk, that is, the highest revision with a number consisting of two fields. N umbers with more than two 
fields are needed for branches. For example, to start a branch at revision 1.3, invoke 

ci -rl.3.1 f.c 

This command starts a branch numbered 1 at revision 1.3, and assignsthe number 1.3.1.1 to the new revision. For more 
information about branches, see rcsfiie(5). 

AUTOMATIC IDENTIFICATION 

RCS can put special strings for identification into your source and object code. T o obtain such identification, place the 
marker: 

$Id$ 

into your text, for instance inside a comment. RCS will replace this marker with a string of the form: 

$Id: filename revision date time author state $ 

With such a marker on the first page of each module, you can always see with which revision you are working. RCS keeps 
the markers up-to-date automatically. T o propagate the markers into your object code, simply put them into literal character 
strings. In C, this isdoneasfollows: 
static char rcsid[] = "$Id$"; 

The command idem extracts such markers from any file even object code and dumps. Thus, idem lets you find out which 
revisions of which modules were used in agiven program. 

You may also find it useful to put the marker $Log$ into your text, inside a comment. This marker accumulates the log 
messages that are requested during checkin. Thus, you can maintain the complete history of your file directly inside it. There 
are several additional identification markers; see co(l) for details. 

IDENTIFICATION 

Author: Walter F. Tichy. 

M anual Page Revision: 5.3; Release D ate: 1993/11/03. 

Copyright© 1982,1988,1989 Walter F. Tichy. 

Copyright© 1990,1991,1992,1993 Paul Eggert. 

SEE ALSO 

ci(l), co(l), ident(l), ncs(l), rcsdiff(l), rcsintro(l), rcsmerge(l), rlog(l) 

"RCS—A System forVersion Control’' by Walter F. Tichy, software Practice & Experience 15, 7 (July 1985), pages 
637-654. 

GNU,3 November 1993 
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rcsmerge — M ergeRCS revisions 

SYNOPSIS 


rcsmerge [options] file 
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DESCRIPTION 

rcsmerge incorporates the changes between two revisions of an RCS file into the corresponding working file. 

Pathnames matching an rcs suffix denote RCS files; all others denote working files. N ames are paired as explained in ci(l). 

At least one revision must be specified with one of the options described in the next subsection, usually -r. At most two 
revisions may be specified. If only one revision is specified, thelatest revision on the default branch (normally the highest 
branch on the trunk) isassumed forthesecond revision. Revisionsmay be specified numerically or symbolically. 

rcsmerge pri nts a warning if there are overlaps, and delimits the overlapping regions as explained in merge(l). The command 
is useful for incorporating changes i nto a checked-out revision. 

OPTIONS 

-A 

-E, -e 

-ks ubst 

-p[r ev ] 

-q [ r e v ] 

-r[rev] 

-T 
-V 
-Vn 

-xsuf f i xes 
-zzone 

EXAMPLES 

Suppose you have released revision 2.8 oft.c. Assume, furthermore that after you complete an unreleased revision 3.4, you 
receive updates to release 2.8 from someone else. T o combine the updates to 2.8 and your changes between 2.8 and 3.4, put 
theupdatesto 2.8 into filet .c and execute 

rcsmerge -p -r2.8 -r3.4 f.c >f.merged.c 

Then exami net .merged, c. Alternatively, if you want to save the updates to 2.8 in the RCS file, check them in as revision 
2. 8 . 1.1 and execute co -j: 

ci -r2.8.1.1 f.c 

co -r3.4 -j2.8:2.8.1.1 f.c 

As another example, thefollowing command undoes the changes between revision 2.4 and 2.8 in your currently checked out 
revision in f.c: 

rcsmerge -r2.8 -r2.4 f.c 

Note theorder of the arguments, andthatf.c will be overwritten. 

ENVIRONMENT 

rcsinit Options prepended to the argument list, separated by spaces. Seeci(l) for details. 

DIAGNOSTICS 

Exit status is 0 for no overlaps, i for some overlaps, 2 for trouble. 


0 utput conflicts using the -a style of ditf3(l), if supported by ditf3. This merges all changes leadi ng 
fromtiie2 to fiie3 into fiiei, and generates the most verbose output. 

These options specify conflict styles that generate less information than -a. Seeditf3(l) for details. The 
default is -e. W ith-e, rcsmerge does not warn about conflicts. 

U sesubst -style keyword substitution. See co(l) for details. For example; -kk -ri.i -ri .2 ignores 
differences in keyword values when merging the changes from 1.1 to 1.2. It normally does not make sense 
to merge binary files as if they were text, so rcsmerge refuses to merge files if -kb expansion isused. 

Send the result to standard output i nstead of overwriting the working file. 

Run quietly; do not print diagnostics. 

M erge with respect to revision r e» . H ere an empty r ev stands for the latest revision on the default branch, 
normally the head. 

This option has no effect; it is present for compatibility with other rcs commands. 

Print RCS'sversion number. 

Emulate RCS version n. Seeco(l) for details. 

Use suf f i *es to characterize RCS files. Seeci(l) for details. 

Use zone as the time zone for keyword substitution. Seeco(l) for details. 
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IDENTIFICATION 

Author: Walter F. Tichy. 

M anual Page Revision: 5.6; Release D ate: 1995/06/01. 

Copyright© 1982,1988,1989 Walter F. Tichy. 

Copyright© 1990,1991,1992,1993,1994,1995 Paul Eggert. 

SEE ALSO 

ci(l), co(l), ident(l), merge(l), rcs(l), rcsdiff(l), rcsintro(l), rlog(l), restile(5) 

"RCS—A System forVersion Control” by Walter F. Tichy, software-practice & Experience 15, 7 (July 1985), pages 
637-654. 

GNU, 1 Junel995 


rdist 

rdist— Remote file distribution program 

SYNOPSIS 

rdist [-nqbRhivwy] [-f distfile] [-d var=v a I ue ] [ - m host ] [name ...] 
rdist [-nqbRhivwy] -c name ... [login@host:dest] 


DESCRIPTION 

rdist is a program to maintain identical copies of files over multiple hosts. It preserves the owner, group, mode, and mtime 
of files if possible and can update programs that are executing, rdist reads commands from distfile to direct the updating 
of files and/or directories. 

Options specific to the first synopsis form: 

If distfile is -, the standard input is used. 

-f distfile Use the specified distfile. 

If either the -f or - option is not specified, the program looks first for distfile, then Distfile to use as the input. If no 
names are specified on the command line rdist will update all ofthefilesand directories listed in distfile. Otherwise, the 
argument is taken to be the name of a file to be updated or the label of a command to execute. If label and filenames conflict, 
it is assumed to be a label. These may be used together to update specific files using specific commands. 

Options specific to the second synopsis form: 

-c Forces rdist to interpret theremainingargumentsasasmall distfile. 

The equivalent distfile is as follows: 
name ... -i login@ host install dest ; 


Options common to both forms: 


-b 

-d var =va I ue 


-h 


-m host 


Binary comparison. Perform a binary comparison and update files if they differ rather than comparing 
dates and sizes. 

Define var to haven a i ue. The -d option is used to define or override variable definitions in the distfile. 
value can be the empty string, one name, or a list of names surrounded by parentheses and separated by 
tabs and/or spaces. 

Follow symbolic links Copy the file that the I ink points to rather than the link itself. 

Ignore unresolved links rdist will normally try to maintain the link structure of files being transferred and 
warn the user if all the li nks cannot be found. 

Limitwhich machi nes are to beupdated. M ultiple -m arguments can be given to limit updates to asubset 
of the hosts listed in thedistfiie. 
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-n Print the commands without executing them. This option is useful for debugging disttiie. 

-q Quiet mode. Filesthat are being modified are normally printed on standard output. The -q option 

suppresses this. 

-R Remove extraneous files. If a directory is being updated, any filesthat exist on the remote host that do not 

exist in the master directory are removed. This is useful for maintaining truly identical copies of directo¬ 
ries. 

-v Verify that the files are up-to-date on all the hosts. Any filesthat are out-of-date will be displayed, but no 

fileswill be changed nor any mail sent. 

-w Whole mode. The whole filename is appended to the destination directory name. N ormally, only the last 

component of a name is used when renaming files. This will preserve the directory structure of the files 
being copied instead of flattening the directory structure. For example, renaming a list of files such as 
dirl / fl dir2/f2 to dir3 would Create files dir3/dir1 /fl and dir3/dir2/f2 instead Of dir3/f1 and dir3/f2. 

-y Younger mode. Files are normally updated if their mtime and size (see stat(2)for more details) disagree. 

The -y option causes rdist not to update files that are younger than the master copy. This can be used to 
prevent newer copies on other hosts from being replaced. A warning message is printed for files that are 
newer than the master copy. 

disttiie contains a sequence of entries that specify thefiles to be copied, thedestination hosts, and whatoperationsto 
perform to do the updating. Each entry has one of the following formats: 

<variable name>'=' <nane list> 

[label: ]<source list> destination listxcommand list> 

[label:]<source list> <time_stamp file><command list> 

The first format is used for defining variables. The second format is used for distributing files to other hosts. The third 
format is used for making lists of filesthat have been changed si nee some given date. The source list specifies a list of files 
and/or directories on the local host that are to be used as the master copy for distribution. Thedestination list is the list of 
hosts to which thesefilesareto be copied. Each file in the source list is added to a list of changes if the file is out-of-date on 
the host that is being updated (second format), or the file is newer than the timestamp file (third format). 

Labels are optional. They are used to identify a command for partial updates. 

N ewlines, tabs, and blanks are only used as separators and are otherwise ignored. Comments begin with # and end with a 
newline 

Variables to be expanded begin with $ followed by one character or a name enclosed in curly braces (see the examples at the 
end). 

T he Source and destination lists have the following format: <name> or '(' <zero or more names separated by white-space> 
')'■ 

The shell meta characters [,],{,},*, and ? are recognized and expanded (on the local host only) in the same way ascsh(l). 
They can be escaped with a backslash. The • character is also expanded in thesameway ascsh(l) but isexpanded separately 
on the local and destination hosts. W hen the -w option is used with a filename that begins with ', everything except the 
homedirectory isappended to thedestination name. Filenames that do not begin with / or' use thedestination user'shome 
di rectory as the root di rectory for the rest of the fi lename. 

The command list consists of zero or more commands of the following format: 

'install 1 <options> opt_dest_name 
'notify' <name list> ';' 

' except' <name list> ';' 

'except_pat' <pattern list> ';' 

'special' <name list> string ';' 

The install command is used to copy out-of-date files and/or directories. Each source file iscopied to each host in the 
destination list. Directories are recursively copied in thesameway. opt_dest_name isan optional parameter to renamefiles. If 
no install command appears in the command list or the destination name is not specified, the source filename is used. 




rd/st 



D i rectories in the path name will be created if they do not exist on the remote host. To help prevent disasters, a nonempty 
directory on a target host will never be replaced with a regular file or a symbolic link. H owever, under the -r option, a 
nonempty directory will be removed if the corresponding filename is completely absent on the master host. The options are 
-r, -h, -i, -v, -w, -y, and -b and have the same semantics as options on the command line except they only apply to the files 
in the source list. The login name used on the destination host is the same as the local host unless the destination name is of 
the format iogin@host. 

The notify command is used to mail the list of files updated (and any errors that may have occurred) to the listed names. If 
no e appears in the name, the destination host is appended to the name (for example namei@host, name 2 @host). 

The except command is used to update all of the files in the source list except for the files listed in namelist. This is usually 
used to copy everything in a directory except certain files. 

T he except_pat command is like the except command except that pattern list is a list of regular expressions (see ed< 1) for 
details). If oneof thepatternsmatchessomestringwithin afilename thatfilewill beignored. Note that because \ isaquote 
character, it must be doubled to become part of the regular expression. Variables are expanded in pattern list, but not shell 
file pattern-matching characters. To include a $, it must be escaped with \. 

The special command is used to specify sh(l) commands that are to be executed on the remote host after the file in name 
list isupdated or installed. If the name list is omitted, then the shell commands will be executed for every file updated or 
installed. Theshell variableFUE is set to the current filename before executing the commands in string. string starts and 
ends with double quotes (■) and can cross multiple lines in distfiie. M ultiple commands to theshell should be separated by 
a semicolon. Commands are executed in the user's home directory on the host being updated. The special command can be 
used to rebuild private databases, and so on after a program has been updated. 

Thefollowing isasmall example: 

HOSTS = ( matisse root@arpa ) 

FILES = ( /bin /lib /usr/bin /usr/games 

/usr/include/{*.h,{stand,sys,vax*,pascal,machine}/*.h 

/usr/lib /usr/man/man? /usr/ucb /usr/local/rdist ) 

EXLIB = ( Mail.rc aliases aliases.dir aliases.pag crontab dshrc sendmail.cf 
sendmail.fc sendmail.hf sendmail.st uucp vfont ) 

${FILES} -> ${HOSTS} install -R ; except /usr/lib/${EXLIB> ; except /usr/games/lib ; 
special /usr/lib/sendmail "/usr/lib/sendmail -bz" ; 

srcs: /usr/src/bin -> arpa except pat ( \\.o\$ /SCCS\$); 

IMAGEN = (ips dviimp catdvi) 

imagen: /usr/local/${IMAGEN} -> arpa install /usr/local/lib ; notify ralph ; 

${FILES} :: stamp.cory notify root@cory ; 

FILES 

distfiie Input command file 

/tmp/rdist* Temporary filefor update lists 

SEE ALSO 

sh( 1), csh(l), stat(2) 

HISTORY 

Therdist command appeared in BSD 4.3. 
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DIAGNOSTICS 

A complaint about mismatch of rdist version numbers may really stem from some problem with starting your shell; for 
example, you are in too many groups. 

BUGS 

Source files must resideon the local host where rdist isexecuted. 

There is no easy way to have a special command executed after all files in a directory have been updated. 

Variable expansion only works for namelists; there should be a general macro facility, 
rdist aborts on filesthat have a negative mti me (beforej an 1,1970). 

There should be a force option to allow replacement of nonempty directories by regular files or symlinks A means of 
updating file modes and owners of otherwise identical filesisalso needed. 

BSD 4.3, 30 D ecember 1993 


reconfig 

reconfig— Convert old Xconfig to new XF86Config 

SYNOPSIS 

reconfig < Xconfig > XF86Config 

DESCRIPTION 

The reconfig program converts the Xconfig file format used in XFree86 versions prior to 3.1 into theXF86Configformat 
currently used. The XF86C onfig format contains more information than the Xconfig format, so manual editing is required 
after converting. 

SEE ALSO 

XFree86(l), XF86Conf ig(4/5), xf86conf ig(l) 

AUTHOR 

Gertjan Akkerman 

BUGS 

Comment lines are stripped out when converting. 


XFree86 Verson 3.1.1 
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ref 

ref— D isplay a C function header 

SYNOPSIS 

ref [-t] [-x] [-c class]... [-f file]... tag 

DESCRIPTION 

ref quickly locates and di splays the header of a function. To do this, ref looks in the tags file for the line that describes the 
function, and then scans the source file for the function. W hen it locates the function, it displays an introductory comment 
(if there is one), the function's declaration, and the declarations of all arguments. 

SEARCH METHOD 

ref uses a fairly sophisticated tag look-up algorithm. If you supply a filename via -f file, then eivis first scans the tags 
file for astatic tag from that file. This search is limited to the tags file in the current directory. 

If you supply a class name via -c class, then eivis searches for a tag from that class. This search is not limited to the 
current directory; You can supply a list of directories in the environment vari able tagpath, and ref will search through the 
tags file in each directory until it finds a tag in the desired class. 

If that fails, ref will then try to look up an ordinary global tag. This search checks all of the directories listed in tagpath, too. 
If the tag being sought doesn't contain any colons, and you haven't given a -x flag, then any static tags in a tags file will be 
treated as global tags. 

If you've given the -t flag, then ref will simply output the tag line that it found, and then exit. Without -t, though, ref 
will search for the tag line It will try to open the source file, which should be in the same directory as the tags file where the 
tag was discovered. If the source file doesn't exist, or is unreadable, then ref will try to open a file called refs in that 
directory. Either way, ref will try to locate thetag, and display whatever itfinds. 

INTERACTION WITH eivis 

ref is used by the eivis shift -k command. If the cursor is located on a word such as splat, in thefile foo.c, then eivis will 
invoke ref with the command ref -f foo.c splat. 

If eivis has been compiled with the -dexternal_tags flag, then eivis will use ref to scan the tags files. This is slower than 
the built-in tag searching, but it allows eivis to access the more sophisticated tag lookup provided by ref. Other than that, 
external tags should act exactly like internal tags. 

OPTIONS 

-t Output tag info, instead of the function header. 

-f file Thetag might be a static function in file. You can useseveral -f flags to have ref consider static tags 

from more than one file 

-c class Thetag might be a member of class class. You can useseveral -c flags to have ref consider tags from 

more than one class. 

FILES 

tags List of function names and their locations, generated by ctags 
refs Function headers extracted from source files (optional) 

ENVIRONMENT 

tagpath List of di rectories to be searched. The elements in the list are separated by either semicolons (for M S-D OS, 

Atari TOS, and AmigaDos), or by colons (every other operating system). For each operating system, ref 
hasabuilt-in default which is probably adequate. 
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NOTES 

You might want to generate a tags file for the directory that contains the source code for standard C library on your system. 
If licensing restrictions prevent you from making the library source readable by everybody, then you can havectags generate 
a rets file, and make refs readable by everybody. 

If your system doesn't come with the library source code, then perhaps you can produce something workable from the lint 
libraries. 

SEE ALSO 

elvis(l), ctags(l) 

AUTHOR 

Steve Kirkendall (kirkenda@cs .pdx.edu) 


reset 

reset— Reset the terminal 

SYNOPSIS 

clear 

DESCRIPTION 

reset calls tput(l) with theciear, rmacs, rmm, rmui, rsi, rs 2 , and rs3 arguments. T his causes tput to send appropriate 
reset stri ngs to the terminal based on information in /etc/termcap (for theG N U or BSD tput) or in theterminfo database 
(forthencurses tput). T his sequence seems to be sufficient to reset the Linux VC's when they start printing "funny¬ 
looking'' characters. For good measure, stty(l) is called with the sane argument in an attempt to get Cooked mode back. 

SEE ALSO 

reset(l), stty(l), tput(l) 

AUTHOR 

Rik Faith (faith@cs.unc. edu) 

Linux0.99,10 October 1993 


resize 

resize— Set termcap and terminal settings to current xterm window size 

SYNOPSIS 

resize [ -u | -c ][-s [ row col ]] 

DESCRIPTION 

resize prints a shell command for setting the term and termcap environment variables to indicate the current size of xterm 
window from which the command is run. For this output to take effect, resize must either be evaluated as part of the 
command line (usually done with a shell alias or function) or else redirected to a file that can then be read in. From theC 
shell (usually known as /bin/csh), thefollowing alias could be defined in the user's. cshrc: 

% alias rs 'set noglob; eval 'resize 11 

After resizing the window, the user would type: 


%rs 



rgb3toppm 



Users of versions of the Bourne shell (usually known as/bin/sh) that don't have command functions will need to send the 

output to a temporary file and the read it back in with the . command: 

$ resize > /tmp/out 

$ . /tmp/out 

OPTIONS 

T he following options may beused with resize: 

-u This option indicates that Bourne shell commands should be generated even if the user's current 

Shell isn't /bin/sh. 

-c Thisoption indicates that C shell commands should be generated even if the user's current shell 

isn't /bin/csh. 

-s [rows columns] T his option indicates that Sun console escape sequences will be used instead of the special xterm 
escape code. If rows and c o i umns are given, resize will ask thexterm to resize itself. However, the 
window manager may choose to disallow the change. 


FILES 

/etc/termcap For the base termcap entry to modify 

" / .cshrc User's alias for the command 

SEE ALSO 

csh(l), tset(l), xterm(l) 

AUTHORS 

M arkVandevoorde(M IT-Athena), Edward M oy(Berkeley) 

Copyright© 1984,1985 byXConsortium 
See X (1) for a complete copyright notice. 

BUGS 

The -u or -c must appear to the left of -s if both are specified. 

X Version 11 Release 6 


rev 

rev— Reverse lines of a file 

SYNOPSIS 

rev [file] 

DESCRIPTION 

The rev utility copies the specified files to the standard output, reversing the order of characters in every line. If no files are 
specified, thestandard input isread. 

21 March 1992 


rgb3toppm 

rgb3toppm — C ombine three portable graymaps into one portable pixmap 
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SYNOPSIS 

rgb3toppmr edpgmf i I e greenpgmfi I e bluepgmfile 

DESCRIPTION 

rgb3toppm reads three portable graymaps as input and combines them and produces one portable pixmap as output. 

SEE ALSO 

ppmtorgb3(l), pgmtoppm(l), ppmtopgm(l), ppm(5), pgm(5) 

AUTHOR 

Copyright© 1991 byjef Poskanzer. 

15 February 1990 


rlog 

riog— Print log messages and other information about RC S files 

SYNOPSIS 

rlog [options ] f i I e ... 


DESCRIPTION 

nog prints information about RCS files. 

Pathnames matching an rcs suffix denote RCS files; all others denote working files. N ames are paired as explained in ci(l). 

riog prints the foil owing information for each RCS file: RCS pathname working pathname head (the number of the latest 
revision on thetrunk), default branch, access list, locks, symbolic names, suffix, total number of revisions number of 
revisions selected for printing, and descriptive text. Thisisfollowed by entries for the selected revisions i n reverse chronologi¬ 
cal order for each branch. For each revision, nog prints revision number, author, dat^time state, number of lines added/ 
deleted (with respect to the previous revision), locker of the revision (if any), and log message. All times are displayed in 
Coordinated Universal Time(UTC) by default; this can be overridden with -z. Without options nog prints complete 
information. T he options below restrict this output. 

-l I gnore RC S fi les that haveno locks set. This is convenient in combination with -h, -i, and -r. 

-r Print only the name of the rcs file. This is convenient for translating a working pathname into an RCS 

pathname. 

- h Print only the RCS pathname, working pathname, head, default branch, access list, locks symbolic names, 

and suffix. 

-t Print the same as -h, plusthe descri ptive text. 

-N Do not print the symbolic names. 

-b Print information about the revisions on the default branch, normally the highest branch on thetrunk. 

-delates Print information about revisions with a checkin dat^time in the ranges given by the semi col on-separated 

list of dates. A range of the form di<d 2 or d 2 >di selects the revisions that were deposited between di and 
d 2 exclusive. A range of the form <d or d> selects all revisions earlier than d.A range of the form d< or>d 
selects all revisions dated later than d. If < or > is followed by =, then the ranges are inclusive, not exclusive. 
A range of the form d selects the single, latest revision dated d or earlier. Thedat^timestringsd, di, and 
d 2 are in the free format explained in co(l). Quoting is normally necessary, especially for < and >. N ote 
that the separator isa semicolon. 

- i [i ockers ] Print information aboutlocked revisions only. In addition, if the comma-separated list! ockers of login 

namesisgiven, ignoreall locks other than those held bythei ockers. Forexample, nog -l -r -iwtt 
rcs/* prints the name of RCS files locked by the user wtt. 



rlog 

-r[r evi si ons ] Print information about revisions given in the comma-separated list revi si ons of revisions and ranges. A 
range revi: rev 2 means revisions revi to rev 2 on the same branch, :rev means revisions from the 
beginning of the branch up to and including rev, and rev: means revi si ons starting with rev to the end of 
the branch containing rev. An argument that is a branch means all revisions on that branch. A range of 
branches means all revisions on the branches in that range. A branch followed by a . means the latest 
revision in that branch. A bare -r with no revisions means the latest revision on the default branch, 
normally the trunk. 

-sst at es Print information about revi si ons whose state attributes match one of the states given in the comma- 

separated list states. 

- w [ i ogi ns ] Print information about revisions checked in by users with login namesappearing in the comma-separated 
list logins. If logins is omitted, the user's login isassumed. 

-t Thisoption has no effect; it is present for compatibility with other res commands. 

-v Print the RCS version number. 

-vn EmulateRCSversion n when generating logs. (See co(l) for more details.) 

-xsuf f i xes Usesuf f i xes to characterize RC S files. (See ci(l) for details.) 

riog prints the intersection of the revisions selected with theoptions -d, - 1 , -s, and -w, intersected with theunion of the 

revisions selected by - band -r. 

-zzone Specifies the date output format, and specifies the default time zone for date in the -ddates option. The 

zone should be empty, a numeric UTC offset, or the special string LTfor local time. The default is an 
empty zone, which uses the traditional RCS format of UTC without any time zone indication and with 
slashes separating the parts of the date; otherwise, times are output in iso 8601 format with time zone 
indication. For example if local timeisjanuary 11,1990, 8 p.m. Pacific Standard Time, eight hours west 
of UTC, then thetime is output as follows: 

option time output 


-z 1990/01/12 04:00:00 (default) 

-zLT 1990-01-11 20:00:00-08 

-z+05:30 1990-01-12 09:30:00+05:30 

EXAMPLES 

H ere are four nog commands: 

rlog -L -R RCS/* 
rlog -L -h RCS/* 
rlog -L -1 RCS/* 
rlog RCS/* 

T he first command prints the names of all RC S fi les i n the subdirectory rcs that have locks T he second command prints 
the headers of those files, and the third prints the headers plus the log messages of the locked revisions. T he last command 
pri nts complete i nformati on. 

ENVIRONMENT 

rcsinit Options prepended to the argument list, separated by spaces. (See ci(l) for details) 

DIAGNOSTICS 

The exit status is zero if and only if all operations were successful. 
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IDENTIFICATION 

Author: Walter F.Tichy 

M anual Page Revision: 5.9; Release D ate: 1995/06/16 
Copyright© 1982,1988,1989 W alter F. Tichy 
Copyright© 1990,1991,1992,1993,1994,1995 Paul Eggert 

SEE ALSO 

ci(l), co(l), ident(l), ncs(l), rcsdiff(l), rcsintro(l), rcsmerge(l), rcsfile(5) 

"RCS-A System for Version Control" by Walter F. Tichy, Software-Practice & Experience 15, 7 (July 1985), pages 637-654. 

BUGS 

The separator for revision ranges in the -r option used to be - instead of:, but this leads to confusion when symbolic names 
contain -.For backwards compatibility, riog -r still supports the old - separator, but it warns about this obsolete use. 

GNU, 16 Junel995 


rlogin 

riogin— Remote login 

SYNOPSIS 

riogin [-8EKLdx] [-e char] [-k realm] [-1 username] host 

DESCRIPTION 

riogin starts a terminal session on a remote host host. 

riogin first attempts to use the Kerberos authorization mechanism, described in the following subsection. If the remote host 
does not support Kerberos, the standard Berkeley authorization mechanism is used. The options are as follows: 

-8 The -8 option allows an eight-bit input data path at all times; otherwise, parity bits are stripped except when the 
remote side's stop and start characters are other than "s/"q. 

-e The -e option stops any character from being recognized as an escape character. When used with the -8 option, 
this provides a completely transparent connection. 

-k The -k option turns off all Kerberosauthentication. 

-l The -l option allows the riogin session to be run in utout mode.(Seetty(4) for details). 

-d The -d option turns on socket debugging (seethesetsockopt(2) man page) on the top sockets used for 
communication with the remote host. 

-e The -e option allows user specification of the escape character, which istheti Ide (') by default. This specification 
may be as a literal character, or as an octal value in the form nnnn. 

-k The -k option requests riogin to obtain tickets for the remote host in realm realm instead of the remote host's 
realm as determined by krb_reaimofhost(3). 

-x The -x option turns on D ES encryption for all data passed via the riogin session. This may impact response time 
and CPU utilization, but provides increased security. 

A line of the form <escape char> disconnects from the remote host. Similarly, the li netscape char>'z will suspend the 
riogin session, and <escape charxdelayed - suspend char> suspends the Send portion Oftherlogin, but allows Output 
from the remote system. By default, the tilde (") character is the escape character, and normally control - y ( " y) is the 
delayed-suspend character. 

All echoing takes place at the remote site, so that (except for delays) the riogin is transparent. Flow control via 's/'q and 
flushing of input and output on interrupts is handled properly. 
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KERBEROS AUTHENTICATION 

Each user may have a private authorization list in thefilein hisor her home directory. Each linein thisfile should contain a 
Kerberos principal name of the form principal, instance (@reaim). If the originating user is authenticated to one of the 
principals named, access is granted to the account. The principal accountname.(@iocaireaim) is granted access if there is 
no file. Otherwise, a login and password will be prompted for on the remote machine as in iogin(l). To avoid certain 
security problems, the file must be owned by the remote user. 

If Kerberos authentication fails, a warning message is printed and the standard Berkeley riogin is used instead. 

ENVIRONMENT 

The following environment variable is utilized by riogin: 
term Determinestheuser'sterminal type 

SEE ALSO 

rsh(l), kerberos(3), krb_sendauth(3), krb_realmofhost(3) 

HISTORY 

The riogin command appeared in BSD 4.2. 

BUGS 

riogin will be replaced by teinet(l) in the near future. 

M ore of the environment should be propagated. 

BSD 4.2, 27July 1991 


rm 

rm— Removefiles 

SYNOPSIS 

rm [-dfirvR] [--directory] [--force] [--interactive] [--recursive] 

[--help] [--version] [--verbose] name... 

DESCRIPTION 

This manual page documents the gnu version of rm. rm removes each specified file. By default, it does not remove directories. 
If a file is unwritable, the standard input is a tty, and the -t or - - force option is not given, rm prompts the user for whether 
to remove the fi le. I f the response does not begi n wi th y or y, the fi le is ski pped. 

GNU rm, like every program that uses the getopt function to parse its arguments, lets you use the - - option to indicate that 
all following arguments are nonoptions. T o remove a file cal led -f in the current directory, you could type either 

rm -- -f 
or 

rm ./-f 

TheU NIX rm program's use of a single - for this purpose predates the development of thegetopt standard syntax. 

OPTIONS 


-d, - -directory 


Remove directories with unlink instead of rmdir, and don't require a directory to be empty before 
trying to unlink it. Only works for the superuser. Because unlinking a directory causes any files in 
the deleted directory to become unreferenced, itiswiseto tsck the filesystem after doing this. 
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-f, - -force Ignore nonexistent files and never prompt the user. 

-i, - - interactive Prompt whether to remove each file. If the response does not begin with y or y, the file is skipped. 

-r, -r, - -recursive Remove the contents of di rectories recursively. 

-v, --verbose Print the name of each file before removing it. 

- -help Print a usage message on standard output and exit successfully. 

- -version Print version information on standard output, then exit successfully. 

GNU File Utilities 

rmdir 

rmdii— Remove empty di rectories 

SYNOPSIS 

rmdi r [-p] [--parents] [--help] [--version] dir... 

DESCRIPTION 

This manual page documents the GN U version of rmdir. rmdir removes each given empty directory. If any nonoption 
argument does not refer to an existing empty directory, it is an error. 

OPTIONS 

-p, - -parents Remove any parent directories that are explicitly mentioned in an argument, if they become empty 

after the argument fi le is removed. 

- -help Print a usage message on standard output and exit successfully. 

- -version Print version information on standard output, then exit successfully. 

GNU File Utilities 

rmmod 

rmmod — U nload loadable modules 

SYNOPSIS 

rnmod [ -r ] module ... 

DESCRIPTION 

rmmod unloads loadable modules from thekernel. 

rmmod tries to unload a set of modules from thekernel, with the restriction that they are not in use and that they are not 
referred to by other modules. 

If more than one module is named on the command line, the modules will be removed in the given order. This supports 
unloading of stacked modules. 

With the option -r, a recursive removal of modules will be attempted. This means that if a top module in a stack is named 
on the command line, all modules that are used by this module will be removed as well, if possible. 

SEE ALSO 

insmod(l), lsmod(l), ksyms(l), modules(2) 
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HISTORY 

The module support was first conceived by Anonymous (as far as I know...). Linux version by BasLaarhoven 
(bas@vimec. ni), 0.99.14 version by J on Tombs (jon@gtex 02 . us. es), extended by Bjorn Ekwall (bj 0 rn@biox. se). 

BUGS 

rmmod might have some but they are well hidden. 

Linux, 14 May 1995 


rnews 

mews — Receive news from a U U C P connection 

SYNOPSIS 

rnews [ - h host ][-v ][-U ][-S master ] [input ] 

DESCRIPTION 

mews reads messages sent by a downstream uucp newsfeed and sends them to the local InterN etN ews server. The message is 
read from the specified input file or standard input if no input is named. 

Ifthe -s flag is used, then rnews will connect to the specified host. If the flag is not used, it will try to connect to the server 
by opening aU NIX-domain stream connection. Ifthat fails, it will try to open aTCP connection to the default remote 
server. 

If the server is not available the message is spooled into a new file created in the /var/spooi/rnews directory. The -u flag 
may be used to send all spooled messages to the server when it becomes avail able again, and can be invoked regularly by 

cron(8). 

When sent over uucp, Usenet articles are typically joined in a single batch to reduce the uucp overhead. Batches can also be 
compressed, to reduce the communication time. If a message does not start with a number sign (#) and an exclamation 
point, then the entire input is taken as a single news article. If it does start with those two characters, then the first line is read 
and interpreted as a batch command. 

If thecommand is#' rnews nnn.wherennn isa number, then the next nnn bytes (starting with the next line) are read as a 
news article. 

If thecommand is#' cunbatch, then the rest of input is fed to thecompress(l) program with the -d flag to uncompress it, 
and the output of this pipe is read as input from rnews. This is for historical compatibility—there is no program named 
cunbatch. A compressed batch will start with a #< cunbatch line, then contain a series of articles separated by #i rnews nnn 
lines. 

If thecommand is any other word, then rnews will try to execute a program with that name in the directory / news/bin/ 
rnews. The batch will be fed into the program's standard input, and the standard output will be read back as input into 
rnews. 

If rnews detects any problems with an article, such as a missing header or an unintelligible reply from the server, it will save a 
copy of the article in the /var/spool/rnews/bad directory. If the - v flag is used, it will print a notice of all such errors on the 
standard error, naming the input file (if known) and printing the first few characters of the input. Errors are always logged 
through sysiog(3). 

Ifthe -h flag is given, or failing that, the environment variable uu_machine is set, then rnews will log theM essage-ID and 
host for each article offered to the server via sysiog(3). Logging will only be done if the value is not an empty string. 

BUGS 

rnews cannot process articlesthat have embedded \os in them. 
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HISTORY 

W ritten by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

innd(8). 
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rpcgen— An RPC protocol compiler 

SYNOPSIS 

rpcgen infile 

rpcgen [-D name[= value]] [-T] [-K secs] infile 
rpcgen -cj-h]-1]-m]-t [-0 outfile] infile 
rpcgen [-1] -s nettype [-0 outfile] infile 
rpcgen -n netid [-0 outfile] infile 

DESCRIPTION 

rpcgen isatool that generates C code to implement an RPC protocol. The input to rpcgen is a language similar to C known 
as RPC language (Remote Procedure Call Language), rpcgen is normally used as in the first synopsis where it takes an input 
file and generatesupto four output files. If the inf iie is named proto.x, then rpcgen will generate a header file in proto.h, 
xdr routines in proto_xdr. c, server-side stubs in proto_svc. c, and client-side stubs in proto_cint. c. 

With the -t option, it will also generate the RPC dispatch table in proto_tbi.i. W ith the -sc option, it will also generate 
sample code that would illustrate how to use the remote procedures on theclient side. Thiscode would be created in 
proto_ciient.c. With the -Ss option, it will also generate a sample server code that would illustrate how to write the 
remote procedures. This code would be created in proto_server.c. Theserver created can be started both by the port 
monitors(for example inetd or listen) or by itself. W hen it isstarted by a port monitor, it creates servers only for the 
transport for which the file descriptor 0 was passed. The name of the transport must be specified by setting up the environ¬ 
mental variable pm_transport. 

When theserver generated by rpcgen is executed, it creates server handles for all the transports specified in netpath 
environment variable, or if it is unset, it creates server handles for all the visible transports from /etc/netconfig file. N ote: 
the transports are chosen at runtime and not at compile time. When theserver is self-started, it backgrounds itself by default. 
A special definesymbol rpc_svc_fg can beused to run theserver process in theforeground. Thesecond synopsis provides 
special features that allow for thecreation of more sophisticated RPC servers. These features include support for user- 
provided #def ines and RPC dispatch tables. The entries in the RPC dispatch table contain 

■ Pointersto the servi ce routi n e corresp on d i n g to th at procedu re 

■ A poi nter to the input and output arguments 

■ The size of these routines 

A server can use the dispatch table to check authorization and then to execute the service routine; a client library may use it 
to deal with the details of storage management and xdr data conversion. The other three synopses shown in the preceding 
paragraph areusedwhen one does not want to generate all theoutput files, but only a particular one. (Some examples of 
their usage is described in the "Example’' subsection.) W hen rpcgen is executed with the -s option, it creates servers for that 
particular class of transports. W hen executed with the -n option, it creates a server for the transport specified by netid. If 
intiie is not specified, rpcgen accepts the standard input. The C preprocessor, cc -e (see cc(l) for details), is run on the 
input file before it is actually interpreted by rpcgen. For each type of output file, rpcgen defines a special preprocessor 
symbol for use by the rpcgen programmer, as follows: 
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rpc_hdr Defined when compiling into header files 

rpc_xdr Defined when compiling into XD R routines 

rpc_svc Definedwhen compiling into server-side stubs 

rpc_clnt Defined when compiling into client-side stubs 

rpc_tbl Defined when compiling into rpc dispatch tables Any line beginning with % is passed directly into the 

output file, uninterpreted by rpcgen. For every data type referred to in infile, rpcgen assumes that there 
exists a routine with the string xdr prepended to the name of the data type If this routine does not exist in 
the R PC/X DR library, it must be provided. Providing an undefined data type allows customization of 
XDR routines. The following options are available 

-a Generate all the files including sample code for client and server side. 

-b ThisgeneratescodefortheSunOS4.1 style of rpc. It isfor backwards compatibility. 

This is the default. 

-5 ThisgeneratescodefortheSysVr4styleof rpc. Itisused by the Tran sport 

Independent RPC that is in Svr4 systems. By default, rpcgen generates code for 
SunOS4.1 type of rpc. 

-c Compile into XDR routines. 

-c Generate code in ANSI C. This option also generates code that could be compiled 

with the C++ compiler. Thisisthe default. 

-k G enerate code i n K&R C. T he default is AN SI C. 

- on a me [ =v a i u e ] D efi ne a symbol name. Equivalent to the#define directive in the source. If no vai ue 
is given, v a i ue isdefined as i. T his option may be specified more than once. 

-h CompileintoC data-definitions (a header file), -t option can be used in conjunc¬ 

tion to producea header file that supports RPC dispatch tables. 

-i Generate a service that can be started from inetd. The default is to generate a static 

service that handles transports selected with -s. Using -i allows starting a service by 
either method. 

-k secs By default, services created using rpcgen wait 120 seconds after servicing a request 

before exiting. That interval can be changed using the -k flag. T o create a server that 
exits immediately upon servicing a request, -k ocan be used. To create a server that 
never exits, theappropriateargument is -k -i. 

When monitoring for a server, some port monitors, such asiistenflM ), always 
spawn a new process in response to a service request. If it is known that a server will 
be used with such a monitor, the server should exit immediately on completion. For 
such servers, rpcgen should be used with - k - i . 

-l Compile into client-side stubs. 

-m Compile into server-side stubs, but do not generate a main routine. This option is 

useful for doing callback-routines and for users who need to write their own main 
routine to do initialization. 

-n neti d C ompile into server-side stubs for the transport specified byneti d. There should be 

an entry for neti d in thenetcontig database. This option may be specified more 
than once so as to compile a server that serves multiple transports. 

-n Usethenewstyleof rpcgen. This allows procedures to have multiple arguments. It 

also uses the style of parameter passing that closely resemblesC. So, when passing an 
argument to a remote procedure, you do not have to pass a poi nter to the argument 
but the argument itself. This behavior is different from the old style of rpcgen- 
generated code. T he new style is not the default case because of backwards 
compati bility. 

-o outf i i e Specify the name of the output file. If none is specified, standard output is used (c, 

-h, -l, -m, -n, -s, -sc, -ss, and -t modesonly). 
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-s net t y pe 


-Sc 


-Ss 


-t 

-T 


C ompile into server-side stubs for all the transports belonging to the class nettype. 
The Supported classes are netpath, visible, circuit_n, circuit_v, datagram_n, 
datagram^, tcp, and udp. See rpc(3N ) for the meani ngs associated with these 
classes. This option may be specified more than once. Note: The transports are 
chosen at runtimeand not at compiletime. 

G enerate sample code to show the use of remote procedure and how to bi nd to the 
server before calling the client-side stubs generated by rpcgen. 

Generate skeleton code for the remote procedures on the server side. You would 
need to fill in theactual code for the remote procedures. 

Compile into RPC dispatch table. 

Generate the code to support RPC dispatch tables. T he options - c, -h, - 1 , -m, u, 
and -t are used exclusively to generate a particular type of file while the options -d 
and -Tare global andean be used with the other options. 


NOTES 

TheRPC language does not support nesting of structures. As a workaround, structures can be declared atthetop level, and 
their name used inside other structures in order to achieve the same effect. N ame clashes can occur when using program 
definitions because the apparent scoping does not really apply. M ost of these can be avoided by giving unique names for 
programs, versions, procedures, and types. The server codegenerated with the -n option refers to the transport indicated by 
netid and hence is very site-specific. 

EXAMPLE 

Thefollowing example: 

$ rpcgen -T prot.x 

generates five files: prot. h, prot_clnt .c, prot_svc.c, prot_xdr .c, and prot_tbl.i. 

This example 

$ rpcgen -h prot.x 

sendstheC data-definitions(headerfile) to thestandard output. 

T o send the test version of the -dtest, server-side stubs for all the transport belonging to the class datagrams to standard 
output, use 

$ rpcgen -s datagram_n -DTEST prot.x 

T o create the server-side stubs for the transport indicated by net i d tcp, use 

$ rpcgen -n tcp -o prot_svc.c prot.x 

SEE ALSO 

cc( 1). 

rsh 

rsh — Remote shell 

SYNOPSIS 

rsh [ - Kdnx ] [-k realm] [-1 username] host command 

DESCRIPTION 


rsh executes command On host. 
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rsh copies its standard input to the remote command, the standard output of the remote command to its standard output, 
and the standard error of the remote command to its standard error. Interrupt, quit, and terminate signals are propagated to 
the remote command; rsh normally terminates when the remote command does. The options are as follows: 

-k T urns off all Kerberos authentication. 

-d Using setsockopt(2), turns on socket debugging on theTCP sockets used for communication with the remote 
host. 

-k Causes rsh to obtain tickets for the remote host in realm instead of the remote host's realm as determined by 
krb_realmof host(3). 

-i By default, the remoteusernameisthesameasthe local username. The -1 option allows the remote name to be 
specified. Kerberos authentication isused, and authorization is determined as in riogin(l). 

-n The -n option redirects input from the special de/ice. (See the "Bugs" section of this manual page.) 

-x The -x option turns on D ES encryption for all data exchange. This may introduce a significant delay in response 

time. 

If no command is specified, you will be logged in on the remote host using riogin(l). 

Shell metacharacters that are not quoted are interpreted on local machine, while quoted metacharacters are interpreted on 
the remote machine. For example, the command: 
rsh otherhost cat remotefile » localfile 

appends the remote file remotefile to the local file locaifiie, while 
rsh otherhost cat remotefile » other remotefile 

appends remotefile to other remotefile. 

FILES 

/etc/hosts 

SEE ALSO 

rlogin(l), kerberos(3), krb sendauth(3), krb_realmof host(3) 

HISTORY 

The rsh command appeared in BSD 4.2. 

BUGS 

If you are using csh(l) and put a rsh in the background without redirecting its input away from the terminal, it will block 
even if no reads are posted by the remote command. If no input is desired you should redirect the input of rsh to using the 
-n option. 

You cannot run an interactive command (rogue(6) or vi(l), for example) using rsh; usenogin(l) instead. 

Stop signals stop the local rsh process only; this is arguably wrong, but currently hard to fix for reasons too complicated to 
explain here. 

BSD 4.2, 24 July 1991 


rstart 

rstart—A sample implementation of a Remote Start client 

SYNOPSIS 


rstart [-c context ] [-g] [-1 username] [-v]hostnameco mma nd a r gs 
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DESCRIPTION 

rstart isa simple implementation of a Remote Start client as defined in "A Flexible Remote Execution Protocol Based on 
rsh." It uses rsh as its underlying remote execution mechanism. 

OPTIONS 

-c context 

-g 

-1 u s e r n a me 
- v 

NOTES 

This is a trivial implementation. Far more sophisticated implementations are possibleand should be developed. 

Error-handling is nonexistent. W ithout -v, error reports from the remote are discarded silently. With -v, error reports are 
displayed. 

T he sdisplay environment variable is passed. If it starts with acolon, thelocal hostname is prepended. The local domain 
nameshould be appended to unqualified hostnames, but isn't. 

The$sEssioN_MANAGER environment variable should be passed, but isn't, 
xi i authority information is passed for the current display. 

ice authority information should be passed, but isn't. It isn't completely clear how rstart should select what ICE authority 
information to pass. 

Even without -v, thesample rstart helper will leave a shell waiting for the program to complete. Thiscauses no real harm 
and consumes relatively few resources, but if it is undesirable it can be avoided by explicitly specifying the exec command to 
the Shell, for example, 0 rstart somehost exec xterm. 

This is obviously dependent on the command interpreter being used on the remote system; the example given will work for 
the Bourne and C shells. 

SEE ALSO 

rstartd(l), rsh(l), "A Flexible Remote Execution Protocol Based on rsh" 

AUTHOR 

Jordan Brown, Quarterdeck Office Systems 

X Verson 11 Releas6 


This option specifies the corn ext in which the command is to be run. A context specifies a general 
environment the program is to be run in. The details of this environment are host-specific; the intent is 
that the client need not know how the environment must be configured. If omitted, the context defaults to 
x. This should be suitable for running x programs from the host's "usual" x installation. 

Interprets command asagener/ccommand, as discussed in the protocol document. This is intended to allow 
common applications to be invoked without knowing what they are called on the remote system. 
Currently, the only generic commands defined are Terminal, LoadMonitor, Listcontexts,and 
ListGenericCommands. 

This option is passed to the underlying rsh; it requests that the command be run as the specified user. 
Thisoption requests that rstart beverbosein its operation. Without this option, rstart discards output 
from the remote's rstart helper, and directs the rstart helper to detach the program from the rsh 
connection used to start it. W ith thisoption, responses from the helper are displayed and the resulting 
program isnot detached from the connection. 


rstartd 

rstartd — A sample implementation of a Remote Start rsh helper 
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SYNOPSIS 

rstartd 

rstartd.real [-c configfilename] 

DESCRIPTION 

rstartd is an implementation of a Remote Start "helper" as defined in "A Flexible Remote Execution Protocol Based 
on rsh.” 

This document describes the peculiarities of rstartd and how it is configured. 

OPTIONS 

-c conf i gf i i ename This option specifies the global configuration file that rstartd isto read. N ormally, rstartd isa 
shell script that invokes rstartd. real with the -c switch, allowing local configuration of the 
location of the configuration file. If rstartd. real is started without the -c option, it reads 
<xRoot>/nb/xi i /rstart/contig, where<xRoot> refers to the root of theXll install tree. 

INSTALLATION 

It is critical to successful interoperation of the Remote Start protocol that rstartd be installed in a directory that is in the 
default search path, so that default rsh requests and them will be able to find it. 

CONFIGURATION AND OPERATION 

rstartd is by design highly configurable. One would like things I ike configuration file locations to be fixed, so that users and 
administrators can find them without searching, but reality is that no two vendors will agree on where things should go, and 
nobody thinks the original location is "right." Thus, rstartd allows the relocation of all of its files and directories. 

rstartd has a hierarchy of configuration files that are executed in order when a request is made. They are global config, per¬ 
user ("local”) config, global per-context config, per-user ("local”) per-context config, config from request. 

As you might guess from the presence of config from request, all of the config files are in the format of an rstart request, 
rstartd defines a few additional keywords with the internal - prefix for specifying its configuration. 

rstartd starts by reading and executing the global config file. This file will normally specify the locations of the other 
configuration files and any system-wide defaults. 

rstartd will then read the user's local config file, default name$HOME/. rstart. 
rstartd will then start interpreting the request. 

Presumably, one of the first lines in the request will be a context line. The context nameisconverted to lowercase, 
rstartd will read the global config file for that context, default name<xRoot>/iib/xi i / rstart/contexts/<name>, if any. 

It will then read the user's config file for that context, default name $home/. rstart. contexts/<name>, if any. 

(If neither ofthese exists, rstartd aborts with a Failure message.) 

rstartd will finish interpreting the request, and execute the program specified. This allows the system administrator and the 
user a large degree of control over the operation of rstartd. The administrator has final say, because the global config file 
doesn't need to specify a per-user config file. If it does, however, the user can override anything from the global file, and can 
even completely replace the global context config files. 

The config fi les have a somewhat more flexible format than requests do; they are allowed to contain blank lines and lines 
beginning with # are comments and ignored. (#s in the middle of lines are data, not comment markers.) 
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Any commands run are provided a few useful pieces of information in environment variables. The exact names are 
configurable, but the supplied defaults are 


$RSTART_CONTEXT 

$RSTART_GLOBAL_CONTEXTS 

$RSTART_LOCAL_CONTEXTS 

$RSTART_GLOBAL_COMMANDS 

$RSTART_LOCAL_COMMANDS 


The name of the context 

The global contexts directory 

The local contexts directory 

The global generic commands directory 

The local generic commands directory 


$rstart_{global,local}_contexts should contain one special file ©List, which contains a list of the contexts in that 
directory in the format specified for Listcontexts. The supplied version of Listcontexts will cat both the global and local 
Copies Of ©List. 


Generic commands are searched for in several places: (defaults) 


Per-user per-context directory 
Global per-context directory 
Per-user all-contexts directory 


$HOME/.rstart.commands/<context> 
<XRoot>/lib/X11/rstart/commands/<context> 
$HOME/.rstart.commands 


Global all-con texts directory (<XRoot>/lib/X11/rstart/commands) 

(Yes, this means you can't have an all-contexts generic command with the same name as a context. It didn't seem I ike a big 
deal.) 


Each of these directories should have a file cal led ©List that gives the names and descriptions of the commands in that 
directory in the format specified for ListGenericcommands. 


CONFIGURATION KEYWORDS 

There are several special rstart keywords defined for rstartd configuration. Unless otherwise specified, there are no 
defaults; related features are disabled in this case. 

internal-Registries n a me ...—G ives a space-separated I ist of misc registries that this system understands. (Registries 
other than these are accepted but generate a warning.) 

Internal - Local - Default relative_f ilename — G ives the name($HOME relative) Of the per-USer COnfig fi le. 
internal-global-contexts absoiute_directory_name— G ives the name of the system-wi de contexts di rectory. 
internal-local-contexts reiat ive_directory_name— G ives the name (shome relative) of the per-user contexts directory. 
internal-global-commands absoiute_directory_name— G ives the name of the system-wi de generi c commands directory. 

internal-local-commands reiative_directory_name— G ives the name (shome relative) of the per-user generic com¬ 
mands directory. 

internal-variable-prefix prefix— Gives the prefix for the configuration environment variables rstartd passes to its 
kids. 

INTERNAL-AUTH-PROGRAM authscheme program argv[0] argv[ 1 ]. . .— Specifies the program to run to Set up authentica¬ 
tion for the specified authentication scheme, program argv[@] ... gives the program to run and its arguments, in the same 
form as the exec keyword. 

internal-auth-input authscheme— Specifies the data to be given to the authorization program as its standard input. Each 
argument ispassed as a single line. $ n, wheren is a number, is replaced by the nth argument to the auth authscheme argi 
arg 2 .. . line. 

internal-print arbitrary text— Prints its arguments as a D ebug message. M ostly for rstartd debugging, but could be 
used to debug configfiles. 
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NOTES 

When using the C shell, or any other shell that runs a script every time the shell is started, the script may be run several 
times. In theworst case, the script may be run three times: By rsh, to run rstartd; by rstartd, to run the specified 
command; by the command, such as xterm. 

rstartd currently limits lines, both from config files and requests, to bufsiz bytes. 

detach is implemented by redirecting file descriptors 0 , 1 , and 2 to / dev/nun and forking before executing the program. 
cmd is implemented by invoking $shell (default /bin/sh) with -c and the specified command as arguments. 
posix-umask isimplemented in the obvious way. 

Theauthorization programs are run in the same context as the target program—same environment variables, path, and so 
on. Longterm, thismightbeaproblem. 

In thex context, GENERIC-CMD Terminal runs xterm. In theopenwindows context, GENERIC-CMD Terminal runScmdtool. 

In thex context, GENERIC-CMD LoadMonitor runsxload. In theopenwindows context, GENERIC-CMD LoadMonitor runs 
perfmeter. 

generic-cmd Listcontexts lists the contents of ©List in both the system-wide and per-user contexts directories. Itis 
available in all contexts. 

generic-cmd ListGenericcommands liststhe contents of ©List in the system-wide and per-user commands directories, 
including the per-context subdirectories for thecurrent context. It is available in all contexts. 

context None is not implemented. 

CONTEXT Default isreally dull. 

For installation ease, the contexts directory in the distribution contains a file ©Aliases, which lists a context name and 
aliases forthat context. Thisfileisused to make symlinks in thecontexts and commands directories. 

All misc values are passed unmodified as environment variables. 

You can mistreat rstartd in any number of ways, resulting in anything from stupid behavior to core dumps. Other than by 
explicitly running programs, I don't think it can write or delete any files, but there's no guarantee of that. The important 
thing is that (a) it probably won't do anything REALLY stupid and (b) it runs with the user's permissions, so it can't do 
anything catastrophic. 

©List files need not be complete; contexts or commands that are dull or which need not or should not be advertised need 
not be listed. In particular, per-user ©List files should not list things that are in the system-wide ©List files. In the future 
perhaps Listcontexts and ListGenericcommands will automatically suppress lines from the system-wide files when there are 
per-user replacements for those lines. 

Error-handling is OK to weak. In particular, no attempt is made to properly report errors on the exec itself. (Perversely, exec 
errors could be reliably reported when detaching, but not when passing the stain/out socket to theapp.) 

If compiled with -dodti_display_hack, rstartd will work around a bug in sco odt version 1. (1.1?) (The bug isthat thex 
clients are all compiled with a bad library that doesn't know how to look hostnames up using D N S. The fix is to look up a 
hostnamein sdisplay and substitute an ip address.) Thisisatrivial exampleof an incompatibility that rstart can hide. 

SEE ALSO 

rstart(l), rsh(l), "A Flexible Remote Execution Protocol Based on rsh" 

AUTHOR 

Jordan Brown, Quarterdeck Office Systems 


X Version 11 Release 6 
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rup— Remote status display 

SYNOPSIS 

rup [ -dhlt] [host ...] 

DESCRIPTION 

rup displays a summary of the current system status of a particular host or all hosts on the local network. T he output shows 
the current time of day, how long the system has been up, and the load averages. The load average numbers give the number 
of jobs in the run queue averaged over 1, 5 and 15 minutes. 

The following options are available: 

-d For each host, report what its local time is. This is useful for checking time synchronization on a network. 

- u Sort the display alphabetically by hostname. 

-l Sort the display by load average. 

-t Sort the display by up time. 

T he rpc. rstatd(8) daemon must be running on the remote host for this command to work, rup uses an RPC protocol 
defined in /usr/include/rpcsvc/rstat.x. 

EXAMPLE 

example% rup otherhost 

otherhost up 6 days, 16:45, load average: 0.20, 0.23, 0.18 
example% 

DIAGNOSTICS 

rup: rpc: Program not registered— The rpc. rstatd(8) daemon has not been started on the remote host, 
rup: rpc: Timed out— A communication error occurred. Either the network is excessively congested, or the 
rpc. rstatd(8) daemon has terminated on the remote host. 

rup: RPC: Port mapper failure - RPC: Timed out— T he remote host is not runni ng the portmapper (see portmap(8) 
man page), and cannot accommodate any RPC-based services. The host may be down. 

SEE ALSO 

ruptime(l), portmap(8), rpc. rstatd(8) 

HISTORY 

The rup command appeared in SunOS. 

BSD 4.3, 7Junel993 
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rusers— Output who is logged in to machines on local network 

SYNOPSIS 

rusers [ -al] [host ...] 

DESCRIPTION 

The rusers command produces output similar to who, but for the list of hosts or all machines on the local network. For each 
host responding to the rusers query, the hostname with the names of the users currently logged on is printed on each line. 
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Therusers command will wait for one minute to catch late responders. 

The following options are available: 

-a Print all machines responding even if no one is currently logged in. 

-l Print a long format listing. This includes the username hostname, tty that the user is logged in to, the date and 
time the user logged in, the amount of time si nee the user typed on the keyboard, and the remote host the user 
logged in from (if applicable). 

DIAGNOSTICS 

rusers: rpc: Program not registered —T he rpc. rusersd(8) daemon has not been started on the remote host, 
rusers: rpc: Timed out— A communication error occurred. Either the network is excessively congested, or the 
rpc.rusersd(8) daemon has terminated on the remote host. 

rusers: rpc: Port mapper failure - rpc: Timed out— T he remote host is not running the portmapper (see 
portmap(8) for more information), and cannot accommodate any RPC-based services. The host may be down. 

SEE ALSO 

rwho(l), users(l), who(l), portmap(8), rpc. rusersd(8) 

HISTORY 

Therusers command appeared in SunOS. 

BUGS 

T he sorting options are not implemented. 

BSD 4.2, 23 April 1991 
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rwaii— Send a message to users logged on a host 

SYNOPSIS 

rwall host 

DESCRIPTION 

The rwaii command sends a message to the users logged in to the specified host. The message to be sent can be typed in and 
terminated with EOForitcan be in afile 

DIAGNOSTICS 

rwaii: rpc: Program not registered— T he rpc. rwaiid(8) daemon has not been started on the remote host, 
rwaii: rpc: Timed out— A communication error occurred. E ither the network is excessively congested, or the 
rpc. rwaiid(8) daemon has terminated on the remote host. 

rwaii: rpc: Port mapper failure - rpc: Timed out— T he remote host is not runni ng the portmapper, and cannot 
accommodate any RPC-based services. The host may bedown. 

SEE ALSO 

wall(l), portmap(8), rpc. rwalld(8) 

HISTORY 

The rwaii command appeared in SunOS. 


BSD 4.2, 23 April 1991 
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rwho 

rwho— Output who is logged in on local machines 

SYNOPSIS 

rwho -a 

DESCRIPTION 

The rwho command produces output similar to who, but for all machines on the local network. If no report has been received 
from a machinefor 11 minutes, then rwho assumes the machine is down, and does not report users last known to be logged 
in to that machine. 

If a user hasn't typed to the system for a minute or more then rwho reports this idle time. If a user hasn't typed to the system 
for an hour or more, then the user will be omitted from the output of rwho unless the - a flag is given. 

FILES 

/var/rwho/whod.* Information about other machines 

SEE ALSO 

finger(l), rup(l), ruptime(l), rusers(l), who(l), rwhod(8) 

HISTORY 

The rwho command appeared in BSD 4.3. 

BUGS 

This is unwieldy when the number of machines on the local net is large. 

BSD 4.2, 23 April 1991 
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script— M aketypescript of terminal session 

SYNOPSIS 

script [-a] [file] 

DESCRIPTION 

script makes a typescript of everything printed on your terminal. It is useful for students who need a hardcopy record of an 
interactive session as proof of an assignment, as the typescript file can be printed outlaterwith ipr(l). 

If the argument fileisgiven, script saves all dialoguein file. If no filename is given, thetypescript issaved in thefile 
typescript. 

Option: 

-a Append theoutput to fileor typescript, retaining the prior contents 

The script ends when the forked shell exits (a control -d to exit the Bourne shell, sh(l), and exit, logout, or control-d (if 
ignoreeof is not Set) for the C-Shell, csh(l)). 

Certain interactive commands, such asvi(l), create garbage i n thetypescript file Script works best with commands that do 
not manipulate the screen; the results are meant to emulate a hardcopy terminal. 
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ENVIRONMENT 

T hefollowing environment variable is utilized by script: 

shell If the variable shell exists, the shell forked by script will be that shell. If shell is not set, the Bourne shell is 
assumed. (M ost shells set this variable automatically.) 

SEE ALSO 

csh(l) (for the history mechanism) 

HISTORY 

The script command appeared in BSD 3.0. 

BUGS 

script places everything in the log file, including linefeeds and backspaces. This is not what the naive user expects. 

BSD 4, 27July 1991 


sed 

sed— Stream-oriented editor 

SYNOPSIS 

sed [ -hnV ][-e script ][-f script-file ][ - - help ][--quiet ][- - silent ] 
[--version] [--expressions c r i pt ] [ --file=scr i pt - f i I e ] [ f i I e ... ] 


DESCRIPTION 

sed reads the specified files or the standard input if no files are specified, makes editing changes according to a list of 
commands, and writes the results to the standard output. 


OPTIONS 

-h, - -help 

-n, --quiet, - -silent 

-V, --version 

-e script, -- expressi on=scri pt 


-f script-file, --fi I e=scri pt-fi I e 


Print a usage message on standard output and exit successfully. 

Suppress the default output, sed only displays lines explicitly specified for 
output with the p command or the p flag of the s command. T he default 
behavior is to echo each line of input, after edits, to the standard output. 
Print the version number on the standard output and exit successfully. 
Append one or more commands specified in the string s c r i pt to the list of 
commands. If there is just one -e option and no -f options, the -e flag may 
be omitted. 

Append theediting commands from scri pt-fi i e to the list of commands. 


M ultiple -e and -t commands may be specified. Scripts are added to the list of commands to execute in the order specified, 
regardless of their origin. 


USAGE 


OPERATION 

sed operates as follows: 

Each line of input, not including its terminating newline character, is successively copied into a pattern space (a 
temporary buffer). 

All editing commandswhose addresses match that pattern space are sequentially applied to the pattern space. 
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When reaching the end of the command list, the pattern space is written to the standard output (except under -n) with 
an appended newline. 

The pattern space iscleared and the process is repeated for each line in the input. 

With sed, original input files remain unchanged because editing commands only modify a copy of the input. 

Somesed commands use a hold space to save all or part of the pattern space for later retrieval. 

COMMAND SYNTAX 

A sed script consists of commandswith the general form: 

[address[, address ]][!]command[arguments] 

Typically, there is only one command per line, but commands may also be concatenated on a single line by semicolons. 
Whitespace characters may be inserted before the first address and the command portions of the script command. 

ADDRESSES 

A sed command, asindicated, can specify zero, one, ortwo addresses. An address can be 

A line number, represented in decimal. The internal line number count maintained by sed is cumulative across input 
files and is not reset for each input file 

A pattern that is a regular expression, represented by nc patternc, where c is any character except backslash (\) or 
newline. In the address nxabcnxdetx, the second x stands for itself, so the regular expression isabcxdet. H owever, the 
preferred (and equivalent) method to construct a regular expression isto enclose the pattern in slashes— /pattern/. 
Additionally, \n can beused to match any newlinein the pattern space, except for the final newline character. 

A $ character that addresses the last li ne of input. 

GNU sed also implements a new type of address. The address has form n "m, which matches any line where the line 
number modulo misequalton modulo m.lf m is 0 or missing, then i isused in its place. This feature is not specified by 
POSIX. 

T he following rules apply to addressed commands: 

A command linewith no address selects each input line. 

A command linewith one address selects any line matching the address. Several commands accept only one address: =, a, 
i, r,and q. 

A command linewith two comma-separated addresses selects the first matching line and all following lines up to and 
including the line matching the second address. If the second address starts before or is the same line as the first address, 
then only thefirst lineisselected. 

An address followed by \ selects all lines that do not match theaddress. 

REGULAR EXPRESSIONS 

Regular expressions are patterns used in selecting text. For example, the sed command 

/st ri ng/p 

prints all lines containing s t r i ng. 

In addition to specifying string literals, regular expression scan represent classes of strings. Strings thus represented are said to 
be matched by the corresponding regular expression. If it is possible for a regular expression to match several strings in aline, 
then the leftmost longest match istheone selected. 

Thefollowingsymbolsareused in constructing search patterns 

The null regular expression is equivalent to the last regular expression used, 
c Any character c not listed here— including {, >, ,, <, >, ;, and +—matches itself. 

\c Any backslash-escaped character c, except for and +, matches itself. 

1 -in 1 . M atches any single character except newline. 
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M atches any single character, other than newline in char- cl ass.' To include a ] in char - 
c i as s , it must be the first character. A range of characters may be specified by separating the 
end characters of therangewith a for example, a-z specifies the lowercase characters. The 
following literal expressions can also be used in char - cl ass to specify sets of characters: 
[:alnum:] [:cntrl:I [:lower:] [:space:] 

[:alpha:] [:digit:] [:print:] [:upper:] 

[:blank:] [:graph:] [:punct:] [:xdigit:] 

If - appears as the first or last character of char ■ d ass, then it matches itself. All other 
characters inchar-ciass match themselves. 

["char - cl ass ] M atches any single character, other than newline not in c h a r - c i ass.char-ci ass isdefined 

as in the preceding entry. 

If" isthefirst character of a regular expression, then it anchorsthe regular expression to the 
beginning of a line. Otherwise, it matches itself. 

$ If $ isthe last character of a regular expression, it anchorsthe regular expression to the end 

of aline. Otherwise, it matches itself. 

\<, \> Anchorsthesingle-character regular expression or subexpression immediately following it to 

the beginning (\<) or ending (\>)of a word, that is, in ASCII, a maximal string of 
alphanumeric characters, including the underscore (_). 

\(re\) Defines a (possibly null) subexpression re. Subexpressions may be nested. A subsequent 

back reference of the form 1 \n \ where n is a number in the range 1-9, expands to the text 
matched by the nth subexpression. For example the regular expression \<a.c\)\i matches 
the string 'abcabc 1 , but not 'abcadc. Subexpressions are ordered relative to their left 
delimiter. 

* M atches the single-character regular expression or subexpression immediately preceding it 

zero or more times. If* isthefirst character of a regular expression or subexpression, then it 
matches itself. The* operator sometimes yields unexpected results. For example the regular 
expression b* matchesthe beginning of the string 'abbb 1 (as opposed to the substring 
1 bbb 1 ) because a null match is the only leftmost match. 

\+ M atches the single character regular expression or subexpression immediately preceding it 

oneor more times. 

\| M atches the regular expression or subexpression specified before or after it. 

\{n ,m\> or \{n ,\> or \{n\> M atches the single-character regular expression or subexpression immediately preceding it at 
least n and at most m times. If m is omitted, then it matches at least n times. If the comma is 
also omitted, then it matches exactly n times. 

( \group\ ) M atches the enclosed group of regular expressions. 

T he following characters only have special meaning when used in replacement patterns: 

\ Escape the following character. 

\n M atches the nth pattern previously saved by n ( 1 and ■ n), where n is a number from 0 to 9. 

Previously saved patterns are counted from the leftmost position on the line. 

& Printsthe entire search pattern when used in a replacement string. 

COMMENTS 

If the first nonwhite character in a line is a #), sed treats that line as a comment, and ignoresit. If, however, the fi rst such 

lineisof theform: 

#n 



sed runs as if the -n flag were specified. 
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GROUPING COMMANDS 

B races ({,}) can beusedto nest one address within another or to apply multiple commands to the same address: 


[address][, address]{ 
command 1 command 2 
} 


The opening { must end a line and the closing > must be on a line by itself. 


COMMANDS 

The maximum number of permissible addresses for each command is indicated in parentheses in the following list. 

An argument denoted text consists of one or more lines of text. If text is longer than one line in length, then any newline 
characters must be hidden by preceding them with a backslash (\). 

An argument denoted read-filename or write-filename must terminate the command line and must be preceded by 
exactly one space. Each write-filename is created before processing begins. 


( 0 ) 

(0) #c o mme n t 

(0) : I abel 
( 1 ) = 

(1 )a\t ext 

(2) b I abel 

(2) c\t ext 


(2) d 
(2) D 

(2) g 

(2) G 
(2) H 
(2) H 

(1) i\t ext 

( 2 ) 1 


An empty command is ignored. 

The line is a comment and isignored by sed. If, however, thefirst such linein a script is of 
theform #n, then sed behavesasif the -n flag had been specified. 

Affix i abel to a linein the script for a transfer of control by b or t commands. 

Write the current line number on the standard output as a line. 

Append text following each line matched by the address on thestandard output before 
reading the next input line. 

Unconditionally transfer control to the: command bearing the i abel . If no i a be is 
specified, then branch to the end of the script; no more commands are executed on the 
current pattern space. 

Change the pattern space by replacing the selected pattern with t ext . W hen multiple lines 
are specified, all lines in the pattern space are replaced with a single copy of t ext. The end 
result isthat the pattern space is deleted and no further editing commands can be applied 
to it. 

Delete the pattern space, preventing the line from being passed to thestandard output, and 
start the next cycle. 

Delete the initial segment of the pattern space through thefirst newline and start the next 
cycle. 

Replace the contents of the pattern space by the contents of the hold space. 

Append a newline character followed by the contents of the hold space to the pattern space. 
Replacethe contents of thehold space by the contents of thepattern space. 

Append a newline character followed by the contents of thepattern space to thehold space. 
I nsert text by writing it to the standard output. 

Write the pattern space to standard output in a visually unambiguous form. N onprinting 
characters are displayed as either three-digit octal values, preceded by a\, or as one of the 
following character constant escape sequences: 

\\ Backslash 

\a Alert 

\b Backspace 

\t Form-feed 

\n Newline 

\r Carriage-return 

\t T ab 

\v Vertical tab 
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(2) n 

(2) N 

(2) P 
(2) P 

(1) P 

(2) r read-filename 

(2) s/regul arexpression/ 
r epl acement /flags 


w wr i t e - f i I e n a me 
(2) t I abel 

(2) w write-filename 
(2) x 

(2) y/s tri ngl/stri n g 2 / 


Long lines are folded, with the point of folding indicated by a backslash (\) and a newline 
character. The end of every line is marked with a$. 

Copy the pattern space to the standard output. Replace the pattern space with the next line 
of input. 

Append the next line of input to the pattern space with an embedded newline. (The current 
linenumber changes.) 

Print the pattern space to thestandard output. 

C opy the i n iti al segment of the pattern space through the fi rst newI i ne to the standard 
output. 

Quit by transferring control to the end of the script and do not start a new cycle. The 
pattern space is still written to thestandard output. 

Read the contents of read-fi i ename. Place them on the output before reading the next 
input line. 

Substitute the r epi acement string for instances of the r e gu i ar expressi on in the pattern 
space. Any character may be used instead of /. (For a fuller description, see the explanation 
of replacement patterns in the "Regular Expressions” section of this manual page.) flags is 
zero or more of: 

n Substitute for just the nth occurrenceof the regular expression, 
g G lobally substitute for all nonoverlapping instances of the regular expression 
rather than just the first one. 

p Print the pattern space if a replacement was made. 

Append the pattern space to wr i te-f i i ename if a replacement was made. 

Branch to the: command bearing thei a be i if any substitutions have been madesincethe 
most recent reading of an input line or execution of at. If i a be i is empty, branch to the 
end of the script. 

Append the pattern space to wr i t e - f i i e n a me. 

Exchange thecontentsof the pattern and hold spaces. 

Replace all occurrences of characters in st r i ngi with the corresponding character in 
stri n g 2 . T he lengths of s t r i ngi andstri n g 2 must be equal. Any character other than 1 
or newline can be used instead of slash to delimit the strings. W ithin st ri ngi and stri n g 2 , 
the delimiter itself can be used as a literal character if it is preceded by a backslash. 


DIAGNOSTICS 

command only uses one address— A command that takes one address had two addresses specified, 
command doesn'ttake any addresses— A command that takes no addresses had an address specified. 

Extra characters after command— A command had extra text after the end. 

unexpected End-of-file— The end of a script was reached before it should have been. This usually occurs when a 
command is started, but not finished. 

no previous regular expression— A metacharacter calling for a previous regular expression before any regular 
expressionswereused. 

Missing command— An address was not followed by a command, 
unknown command— A command was not one of the ones recognized by sed. 
unexpected 1 ,' — A command had a spurious comma after an address. 

Multiple ■ i ■ s — M ore than one < (exclamation point) was used in acommand. 
unexpected g— A g character was given in a command without a preceding f. 
unexpected f—An f character was given in a command without a following g. 

} doesn't want any addresses —} Should be alone On a line. 
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doesn 1 1 want any addresses— The: command should not be preceded by an address, 
unterminated s command— T he replacement field of the s command should be completed with a / character. 

Multiple p options to s command — T he p option was given morethan oncein an s command. 

Multiple g options to s command— Theg option wasgiven morethan oncein an s command. 

Multiple number options to s command— M orethan one number option wasgiven to an s command, 
unknown option to s— An unknown option wasused for thes command. M aybeyou shouldn't do that, 
strings for y command are different lengths —T here should be a one-to-one mapping between strings for they 
command. 

Missing 1 1 before filename— T here was no space between an r, w, or s///w command, and the filename specified for 
that command. 

Hopelessly evil compiled in limit on number of open file, re-compile sed. — An attempt W3S made to Open 
too many files, no matter how you look at it. 

SEE ALSO 

awk(l), ed(l), grep(l), perl(l), regex(3) 

HISTORY 

A sed command appeared in version 7 AT&T U NIX. 

STANDARDS 

GNU sed is expected to be a superset of the IEEE Stdl003.2 (POSIX) specification. 

CAVEATS 

GNU sed uses the POSIX basic regular expression syntax. According to the standard, the meaning of some escape sequences 
is undefi ned in this syntax; notably \ i and \+. 

As in all GN U programs that use POSIX basic regular expressions, sed interprets these escape sequences as metacharacters. 

So, x\+ matches one or more occurrences of x. abc\ i def matches either abc or def. 

This syntax may cause problems when running scripts written for other versions of sed. Some sed programs have been 
written with the assumption that \ | and \+ match the literal characters | and +. Such scripts must be modified by removing 
the spurious backslashes if they are to be used with GNU sed. 

BUGS 

It has long been noted thatGN U sed is much slower than other implementations. The current bottleneck is the way sed 
reads and writes data files. It should read large blocks at a time (or even map files, where that is supported). When possible it 
should avoid copying its input from one place in memory to another. Patches to make it do those things are welcome! 

Version 2.05, December 1994 
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sessreg— M anage utmp/wtmp entries for non-init clients 

SYNOPSIS 

sessreg [-w wtmp-file] [-u utmp-file] [-1 line-name] [-h host-name] 

[-s s I ot-number ] [-x Xservers-fiI e ] [-t 11ys-fiI e ] [-a] [ -d ] user-name 

DESCRIPTION 

sessreg is a simple program for managing utmp/wtmp entries for xdm sessions. 
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System V has a better interface to / etc /utmp than BSD; it dynamically allocates entries in the file instead of writing them at 
fixed positions indexed by position in /etc/ttys. 

T o manage BSD -style utmp files, sessreg has two strategies. In conjunction with xdm, the -x option counts the number of 
lines in /etc/ttys and then adds to that the number of the line in the xservers file that specifies the display. The display 
name must be specified as the i i ne - name using the -1 option. This sum is used as the si ot - number in /etc/utmp that this 
entry will be written at. In the more general case, the - s option specifies the si ot ■ number directly. If for somestrange reason 
your system uses a file other that /etc/ttys to manage init, the -t option can direct sessreg to look elsewhere for a count 
of terminal sessions. 

Conversely, System V managerswill never need to use these options (-x, -s, and -t). To make the program easier to 
document and explain, sessreg accepts the BSD-specific flags in the System V environment and ignores them. 

BSD also has ahost - name field in the utmp file that doesn't exist in System V. This option is also ignored by the System V 
version Of sessreg. 

USAGE 

In xstartup, placea call like: 

sessreg -a -1 $DISPLAY -x /usr/X11R6/lib/xdm/Xservers $USER 
and in xreset: 

sessreg -d -1 $DISPLAY -x /usr/X11R6/lib/xdm/Xservers $USER 

OPTIONS 

-w wt mp - f i I e 

- u u t mp- f i I e 
-1 I i n e - n a me 

- h h o s t - n a me 

-s slot-number 

-x Xser ver s-fi I e 

-t 11 ys - f i I e 

-a 
-d 

SEE ALSO 

xdm(l) 

AUTHOR 

Keith Packard, M IT X Consortium 


This specifies an alternatewtmp file instead of /usr/adm/wtmp for BSD or /etc/wtmp for sysv. The 
special namenone disables writing records to /usr/adm/wtmp. 

This specifies an alternate utmp file instead of /etc/utmp. The special namenone disables writing 
records to / etc/utmp. 

T his describes the line name of the entry. For terminal sessions, thisisthefinal pathname segment 
of the terminal device filename (for example, ttydo). For x sessions, it should probably be the local 
display name given to the users session (for example, : 0 ). If none is specified, the terminal name 
will be determined with ttyname(3) and stripped of leading components. 

This is set for BSD hosts to indicate that the session was initiated from a remote host. In typical 
xdm usage, this options is not used. 

Each potential session has a unique slot number in BSD systems; most are identified by the 
position of thei i ne- name in the /etc/ttys file This option overrides the default position 
determined with ttys-iot(3). This option is inappropriate for use with xdm, the -x option is more 
useful. 

As x sessions are one-per-display, and each display is entered in this file this options sets the si ot - 
number to be the number of lines in the 11 ys - f i 1 e plus the index into thisfi le that the 1 i ne - name 
isfound. 

This specifies an alternate filethat the -x option will use to count the number of terminal sessions 
on a host. 

This session should be added to utmp/wtmp. 

T his session should be deleted from utmp/wtmp. -a or -d must be specified. 


X Version 11 Release 6 



Parti: User Commands 

setterm 

setterm— Set terminal attributes 

SYNOPSIS 

setterm [ -term t er mi nal name ] 

setterm [-reset ] 

setterm [ -initialize ] 

setterm [ -cursor [onJoff] ] 

setterm [ -keyboard pc[Olivetti!dutch|extended ] 

setterm [ -repeat [onJoff] ] 

setterm [ -appcursorkeys [on|off] ] 

setterm [ -linewrap [on J off] ] 

setterm [ -snow [on J off] ] 

setterm [ -softscroll [onJoff] ] 

setterm [ -defaults ] 

setterm [ -foreground black|red!green!yellow|blue!magenta!cyan|whitejdefault ] 

setterm [ -background black|red!green!yellow|bluejmagenta!cyan|white!default ] 

setterm [ -ulcolor black!grey!redjgreen!yellow!blue!magenta!cyan|white ] 

setterm [ -ulcolor bright redjgreenjyellowjbluelmagentalcyan[white ] 

setterm [ -hbcolor black[grey!redjgreen!yellowjblue]magenta!cyan!white ] 

setterm [ -hbcolor bright red!green!yellow[blue[magenta!cyan!white ] 

setterm [ -inversescreen [on|off] ] 

setterm [ -bold [on J off] ] 

setterm [ -half-bright [on|off] ] 

setterm [ -blink [on[off] ] 

setterm [ -reverse [on j off] ] 

setterm [ -underline [on[off] ] 

setterm [ -store ] 

setterm [ -clear [ alljrest ] ] 

setterm [ -tabs [tabl tab2 tab3 ... ] ] where (tabn = 1-160) 
setterm [ -clrtabs [ tabl tab2 tab3 ... ] where (tabn = 1-160) 
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setterm [ -regtabs [ 1-160 ]] 
setterm [ -blank [ 0-60 ]] 
setterm [ -dump [ 1 - NR CONS ]] 
setterm [ -append [ 1 - NR CONS ]] 
setterm [ -file dumpf i I ename ] 
setterm [ -standout [ attr ]] 

DESCRIPTION 

setterm writes to standard output a character string that will invoke the specified terminal capabilities. Where possible, / 
etc/termcap is consulted to find the string to use. Some options, however, do not correspond to atermcap(5) capability. In 
this case, if the terminal typeisminix-vc or minix-vcam, the string that invokes the specified capabilities on the PC M i nix 
virtual console driver is output. Options that are not implemented by the terminal areignored. 

OPTIONS 

M ost options are self-explanatory. T he less obvious options are as follows: 

-term Can beused to overridetheiERMenvironmentvariable 

-reset D isplays the terminal reset string, which typically resets the terminal to its power on state 

-initialize D isplays the terminal initialization string, which typically sets the terminal's rendering options, and other 

attributes to the default values 

-default Sets the terminal's rendering options to the default values 
-store Stores the terminal's current rendering options as the default values 

Linux0.98, 25 December 1992 

SEE ALSO 

tput(l), stty(l), termcap(5), tty(4) 

BUGS 

D ifferences between theM i nix and Linux versions are not documented. 

AUTHORS 

Gordon Irlam (gordoni@cs.ua.oz.au); adaptation to Linux by Peter M acDonald; enhancements by M ika Liljeberg 

(liljeber@cs.Helsinki.Fl) 

Linux0.98, 25 December 1992 

sgitopnm 

sgitopnm— Convert an SGI image file to a portable anymap 

SYNOPSIS 

sgitopnm [-verbose][SGIf i I e] 

DESCRIPTION 

Reads an SGI image file as input. Produces a PGM image for a two-dimensional (one-channel) input file, and a PPM image 
for a three-dimensional (three or more channels) input file. 
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OPTIONS 

-verbose G ive some information about the SGI imagefile 

BUGS 

Probably 

REFERENCES 

SGI I mage File Format documentation (draft vO.95) byPaul H aeberl i (paui@sgi.com). Available via ftp at 

sgi.com:graphics/SGIIMAGESPEC. 

SEE ALSO 

pnm(5), pnmtosgi(l) 

AUTHOR 

C opyright© 1994 by I ngo W i I ken (ingo .Wilken@informatik. uni -Oldenburg. de). 

29 January 1994 


shar 

shar— C reate shell archives 

SYNOPSIS 

shar [ options ] file ... 
shar -S [ options ] 

DESCRIPTION 

shar creates shell archives (or shar files) that are in text format and can be mailed. These files may be unpacked later by 
executing them with /bin/sh. The resulting archive is sent to standard out unless the -o option is given. A wide range of 
features provide extensive flexibility in manufacturing sharsand in specifying shar "smartness." Archives may be "vanilla" or 
comprehensive. Thismanual page reflects shar version 4.0. 

OPTIONS 

0 ptions have a one-letter version starti ng with - ora long version starting with --. The exceptions are - -help and -- 
version, which do not have short versions. Options can be given in any order. Some options depend on each other: The - o 
option isrequired if the -i or -l option isused. 

The -n option isrequired if the -a option isused. 

See -vin thefollowing list. 

T hese are the available options: 

- - version 

- -help 

-V, --vanilla-operation 


Print the version number of the program on standard output, then immedi¬ 
ately exit. 

Print a help summary on standard output, then immediately exit. 

Produce vanilla sharsthat rely only upon the existence of sed and echo in 
theunsharing environment. In addition, it test must also be supported if 
the -x option isused. The -v silently disables options offensive to the 
network cop (or brown shirt), but does warn you if it is specified with -b, - 
z, -z, -p, or -m (any of which doesormightrequireuudecode, gzipor 
compress in the unsharing environment). 
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v, - - no - verbose 

w, --no-character-count 

n name, --archive-name=n a me 

a, - - net -headers 


s who@where, - -submitter=who@where 
x, -- no - check - existing 

X, - -query-user 
B, - -uuencode 

T, - -text-files 
z, - -gzip 

Z, - - compress 

m, - -no-timestamp 
p, - -intermix-type 

g X, --level-for-gzip=X 
b X, --bits-per-code=X 


Verbose off. disables the inclusion of comments to be output when the 
archive is unpacked. 

DoNOT checkwithwe -c after unpack. T he default isto check. 

N ameof archive to be included in the header of theshar files. (Seethe - a 
switch.) 

Allows automatic generation of headers: 

Submitted by: who@where 
Archive-name: <name>/part## 

The<name> must be given with the -n switch. If name includesa /, then / 
part isn't used. Thus -n xyzzy producesthefollowing: 

xyzzy/part01 

xyzzy/part02 

-n xyzzy/patch produces thefollowing: 

xyzzy/patch01 

xyzzy/patch02 

-n xyzzy/patchoi . producesthefollowing: 
xyzzy/patch01.01 
xyzzy/patch01.02 

Thewho@wherecan be explicitly stated with the -s switch if the default isn’t 
appropriate. who@where is essentially built as 1 whoami 1 uname'. 

Override automatically determined submitter name. 

Overwrite existing files without checking. If neither -x nor -x is specified, the 
unpack will check for and not overwrite existing files when unpackingthe 
archive (unless -c is passed as a parameter to thescriptwhen unpacking). 
Interactively overwrite existing files (D o not use for shars submitted to the 
N et.) 

Treatall files as binary; use uuencode prior to packing. Thisincreasesthesize 
of the archive. The recipient must haveuudecode in order to unpack. (Useof 
uuencode is not appreciated by many on the N et.) 

T reat all fi les as text (default). 

Use gzip and uuencode on all files prior to packing. The recipient must have 
uudecode and gzip (used with -d) in order to unpack. (Useof uuencode and 
gzip is not appreciated by many on the N et.) 

Use compress and uuencode on all files prior to packing. The recipient must 
haveuudecode and compress (used with -d) in order to unpack. (Useof 
uuencode and compress is not appreciated by many on theN et.) Option -c 
is synonymous to -z, but is being depreciated. 

Avoid generating touch commands to restore thefile modification dates 
when unpacking files from the archive. 

Allow positional parameter options. The options -b, -t, -z, and -z maybe 
embedded, and files to theright of theoption will be processed in the 
specified mode. 

When doing compression, use -x as a parameter to gzip. The -g option 
turns on the -z option by default. 

When doing compression, use -bx as a parameter to compress. The -b option 
turns on the -z option by default. 
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-M, --mixed-uuencode 

-P, --no-piping 
-c, --cut-mark 

-f, -- basename 


-d XXX, --here-delimiter=XXX 
-F, - -force-prefix 


-o XXX --output-prefix=XXX 

-1 XX --whole-size-limit=XX 
-L XX --split-size-limit=XX 

-S --stdin-file-list 


M ixed mode. Determine if thefiles are text or binary and archive correctly. 
Files found to be binary are uudecoded prior to packing. (U seof uuencode is 
not appreciated by many on the N et.) 

Use temporary files instead of pipes in theshar file. 

Start the shar with a cut line. A line saying cut her-e is placed at the start of 
each output file. 

Restore by filenameonly, rather than path. This option causes only filenames 
to be used, which is useful when building a shar- from several directories, or 
another directory. N otethat if a directory name is passed to shar-, the 
substructure of that directory will be restored whether -f is specified or not. 
Use xxx to delimit the files in theshar instead of shar_eof. This is for those 
who want to personalize their shar files. 

Forces the p r ef i x character (normally x unless the parameter to the -d 
option starts with x) to be prepended to every line even if not required. This 
option may slightly increase the size of the archive, especially if -Bor -z is 
used. 

Save the archive to files xxx .01 through xxx .nn instead of standard out. 

M ust be used when the -1 or the -l switches are used. 

Limit the output file size to xxk bytes, but don't split input files. 

Limit output file size to xxk bytes and split files if necessary. The archives 
created with this option must be unpacked in correct order. 

Read list of files to be packed from the standard input rather than from the 
command line. Input must be in a form similar to that generated by the 
find command, one filename per line. This switch is especially useful when 
thecommand linewill not hold the I ist of files to be packed. For example: 

find . -type f -print ] sort | shar -S -Z -L50 -o /tmp/big 

If -p is specified on thecommand line, then theoptions -b, -t, -z, and -z 
may be included in the standard input (on a line separate from filenames). 
The maximum number of lines of standard input, filenames, and options 
may not exceed 1024. 


EXAMPLES 

shar *.c > cprog.shar # all C prog sources 

shar -v *.[ch] > cprog.shar # non-verbose, .c and .h files 

shar -B -128 -oarc.sh *.arc # all binary .arc files, into 

# files arc.sh.01 thru arc.sh.NN 

shar -f /lcl/src/u*.c > u.sh # use only the filenames 

WARNINGS 

N 0 chmod or touch isever generated for directories created when unpacking. Thus, if a directory is given to shar, the 
protection and modification dates of corresponding unpacked directory may not match those of the original. 

If a directory is passed to shar, it may be scanned more than once. T herefore one should be careful not to change the 
directory while shar isrunning. 

Be careful that the output file(s) are not included in the inputs or shar may loop until the disk fills up. Be particularly careful 
when a directory is passed to shar that the output files are not in that directory (or a subdirectory of that directory). 

Use of the -b, -z, or -z, and especially -m, may slow the archive process considerably, depending on the number of files. 

Use of -x produces shars that will cause problems with many unshar procedures. Use this feature only for archives to be 
passed among agreeable parties Certainly, -x is not for shell archives that are to be submitted to Usenet. Usage of -b, -z, or 
-z in N et shars will cause you to be flamed off the earth. N ot using -m or not using -f may also get you occasional 
complaints 
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SEE ALSO 

unshar(l) 

DIAGNOSTICS 

There are error messages for illegal or incompatible options; for nonregular, missing, or inaccessible files; or for (unlikely) 
memory allocation failure 

AUTHORS 

shar-(3) is a derived work based on the efforts of the following: J ames G osling at CM U (decvax'microsot 'uw-beavei jim), 

M ichael A. Thompson, D alhousieU niversity, H alifax, N ,S„ Canada, Bill Davidsen (davidsen@sixhub), Richard H. 

Gumpertz (rhgocps.coM), Colas N ahaboo (coiasoavahi.inria.tr), Bill Aten (biiionetagw.com), D ennisBoylan 
(dennis%nanovxogatech. edu), W arren T ucker (wht%n4hgtogatech. edu), and other anonymous persons. J an D jfrv 
(jhdoirfu.se) created the man pages. 

27 September 1990 


shlock 

shiock— Create lock files for use in shell scripts 

SYNOPSIS 

shlock -p p i d -f name [ -b ][-u ][-c ] 

DESCRIPTION 

shiock tries to create a lock file named name and write the process ID pi d into it. If the file already exists, shlock will read 
the process ID from the file and test to see if the process is currently running. If the process exists, then the file will not be 
created. 

shiock exits with a zero status if it was able to create the lock file, or non-zero if the file refers to the currently active process. 

ProcessIDsare normally read and written in ASCII. If the -bflag is used, then they will be written as a binary mt. For 
compatibility with other systems, the - u flag is accepted as a synonym for -b because binary locks are used by many uucp 
packages. 

The foil owing example shows how shiock would be used within a shell script: 

LOCK=/news/lib/LOCK.send 

trap 'rm -f ${LOCK} jexitr 1 2 3 15 

if shlock -p $$ -f ${LOCK} ; then 

# Do appropriate work 

else 

echo Locked by 'cat ${LOCK}' 
fi 

If the -cflag is used, then shiock will not create a lock file but will instead use the file to see if the lock is held by another 
program. If the lock is valid, the program will exit with a non-zero status; if the lock is not valid (that is, invoking shiock 
without the flag would have succeeded), then the program will exitwith azero status. 

HISTORY 

W ritten by Rich $alz (rsaiz@uunet.uu.net) after a description ofHDBUUCP locking given by Peter H oneyman. 
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showrgb 

showrgb— Uncompilean RGB colornamedatabase 

SYNOPSIS 

showrgb [ database ] 

DESCRIPTION 

The showrgb program reads an RGB colorname database compiled for use with thedbm database routines and converts it 
back to source form, printing the result to standard output. The default database is the one that x was built with, and may be 
overridden on the command line Specify the database name without the .pag or .dir suffix. 

FILES 

<xRoot>/iib/xi i /rgb Default database 

X Verson 11 Release 6 


shrinkfile 

shrinktiie— Shrink a file on a line boundary 

SYNOPSIS 

shrinkfile [ -s size ][-v ] file.,. 

DESCRIPTION 

The shrinkfile program shrinks files to a given size, preserving the data at the end of the file T runcation is performed on 
line boundaries, where a line is a series of bytes ending with a newline, \n. There is no line length restriction and files may 
contain any binary data. 

T emporary files are created in the /tmp directory. T he tmpdir environment variable may be used to specify a different 
directory. 

A newline will be added to any nonempty file that does not end with a newline. The maximum file size will not be exceeded 
by this addition. 

By default, files are truncated to zero bytes. The - s flag may be used to change the maximum size. Because the program 
truncates only on line boundaries, thefinal size may be may be smaller then the specified maxi mum. The size parameter 
may end with ak, m, org, indicating kilobyte (1024), megabyte (1048576) or gigabyte (1073741824) lengths. Uppercase 
letters are also allowed. The maxi mum file size is 2147483647 bytes. 

If the -vflag is used, then shrinkfile will print a status line if a file was shrunk. 

HISTORY 

Written by Landon Curt N oil (chongo@toad.com) and Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

sirtopnm 

sirtopnm— Convert a Solitaire file into a portable anymap 

SYNOPSIS 

sirtopnm [si r fiI e ] 
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DESCRIPTION 

Reads a Solitaire I mage Recorder file as input. Produces a portable anymap as output. T he type of the output fi le depends on 
the input file ifit'san MGI TYPE 17 files, a pgm file is written. If it’s an M GI TYPE 11 files, a ppm file is written. The 
program tells you which type it iswriting. 

SEE ALSO 

pnmtosir(l), pnm(5) 

AUTHOR 

Copyright© 1991 by M arvin Landis. 

20 March 1991 


size 

size— List section sizes and total size 

SYNOPSIS 

size [ -A | -B | - -format=c o mp a t i b i I i t y ][--help ] 

[ -d | -o | -x | --radix=number ] 

[ --target=bfd n a me ][-V j --version ] objfile ... 

DESCRIPTION 

TheGN U size utility lists the section sizes and the total size for each of the object files obj file in its argument list. By 
default, one line of output is generated for each object file or each module in an archive. 

OPTIONS 

-A, -B, --format compatibility 


--help 

-d, -o, -x, - -radix number 


--target bf d n a me 

-V, - - version 

SEE ALSO 

binutiis entry in info; The GNU Binary U tilities, Roland H. Pesch (October 1991); ar(l), objdump(l) 

COPYING 

Copyright© 1991 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this 
manual, provided the copyright notice and this permission notice are preserved on all copies. 

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 


Using one of these options, you can choose whether the output from GNU size 
resembles output from System V size (using -a, or - -format=sysv ), or Berkeley 
size (using -b or - -format=berkeiey) . The default is the one-line format similar to 
Berkeley's. 

Show a summary of acceptable arguments and options. 

Using one of these options, you can control whether the size of each section isgiven 
in decimal (-d, or --radix 10 ); octal ( -a, or --radix 8); or hexadecimal (-x, or 
--radix 16 ). In --radix number, only the three values (8, 10 , 1 6) are supported. 
Thetotal size is always given in two radices: decimal and hexadecimal for -d or -x 
output, or octal and hexadecimal if you're using -o. 

You can specify a particular object-code format for objfile as bf dname .Thismay 
not be necessary; size can automatically recognize many formats. (Seeobjdump(l) 
for information on listing availableformats.) 

D isplay version number information on size itself. 
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Permission is granted to copy and distribute translations of this manual into another language, under the above conditions 
for modified versions, except that this permission notice may be included in translations approved by the Free Software 
Foundation instead of in the original English. 

CygnusSupport, 5 N ovember 1991 

sldtoppm 

sidtoppm— Convert an AutoCAD slide file into a portable pixmap 

SYNOPSIS 

sldtoppm [-adjust][-dir][-height|-ysize s ][-info][-lib j -Lib name ][-scale s] 

[ - verbose] [ - width | -xsize s][slidefile] 

DESCRIPTION 

sidtoppm reads an AutoCAD slide file and outputs a portable pixmap. If no siidefiie is specified, input is read from 
standard input. T he ppmdraw library is used to convert the vector and polygon information in the slide file to a pixmap; see 
the file ppmdraw. h for details on this package. 

OPTIONS 

-adjust If the display on which the slide file was created had nonsquare pixels, when the slide is processed with 

sidtoppm and the -adjust option isnot present, thefollowing warning will appear: warning - pixels on 
source screen were non-square. 

Specifying -adjust will correct image width to compensate. Specifying the -adjust option causes 
sidtoppm to scale the width of the image so that pixels in the resulting portable pixmap are square (and 
hence circles appear as true circles, not ellipses). The scaling is performed in the vector domain, before 
scan-converting the objects. The results are, therefore, superior in appearance to what you'd obtain were 
you to perform the equivalent scaling with pnmscaie after the bitmap had been created. 

-dm The input is assumed to bean AutoCAD slide library file. A directory listing each slide in the library is 

printed on standard error. 

-height size Scales the image in the vector domain so it issi ze pixels in height. If no -width or -xsize option is 
specified, thewidth will be adjusted to preserve the pixel aspect ratio. 

-into D ump the slide file header on standard error, displaying the original screen size and aspect ratio among 

other information. 

-lib name Extracts the slide with the given n a me from theslide library given asinput. The specified name isconverted 
to uppercase. 

-Lib name Extracts the slide with the given n a me from theslide library given asinput. Thena me is used exactly as 
specified; it is not converted to uppercase. 

-scale s Scales the image by factors, which may beany floating-point value greater than zero. Scaling is done after 

aspect ratio adjustment, if any. Because scaling is performed in the vector domain, before rasterization, the 
results look much better than runningtheoutput of sidtoppm through pnmscaie. 

-verbose D umps the slide file header and lists every vector and polygon in the file on standard error. 

-width size Scales the image in the vector domain, so it is size pixels wide. If no - height or - ysize option is 
specified, the height will be adjusted to preserve the pixel aspect ratio. 

-xsize size Scales the image in the vector domain so it is si ze pixels wide. If no -height or - ysize option is specified, 
the height will be adjusted to preserve the pixel aspect ratio. 

-ysize size Scales the image in the vector domain so it issi ze pixels in height. If no -width or -xsize option is 
specified, thewidth will be adjusted to preserve the pixel aspect ratio. 

All flags can be abbreviated to their shortest unique prefix. 
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BUGS 

Only Level 2 slides are converted. Level 1 format has been obsolete since the advent of AutoCAD Release 9 in 1987 and was 
not portable across machine architectures. 

Slide library items with names containing 8-bit (such as I SO) or 16-bit (Kanji, for example) characters may not be found 
when chosen with the - lib option unless sidtoppm has been built with character set conversion functions appropriate to the 
locale. You can always retrieve si ides from libraries regard I ess of the character set by using the - Lib option and specifying the 
precise name of library member. U sethe - dir option to list the slides in a library if you're unsure of the exact name. 

SEE ALSO 

AutoCAD ReferenceM anual: "Slide File Format"; pnmscaie(l), ppm(5) 

AUTHOR 

John Walker 
Autodesk SA 

Avenue desChamps-M ontants 14b 
C FI -2074 M ARIN 

Sui sse/ Sch wei zj Svi zzera/ Svizra/ Swi tzerl an d 
Usenet: kelvin@Autodesk.com 

Fax: 038/33 88 15 

Voice 038/33 76 33 

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is 
hereby granted, without any conditions or restrictions. This software is provided "as is” without express or implied warranty. 

AutoCAD and Autodesk are registered trademarks of Autodesk, Inc. 

10 October 1991 
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smproxy— Session M anager Proxy 

SYNOPSIS 

smproxy [-clientld id] [-restore saveFile] 

OPTIONS 

-ciientid id Specifi es the session ID used by smproxy in theprevioussession. 

-restore saveFile Specifies the file used by smproxy to savestatein theprevioussession. 

DESCRIPTION 

smproxy allowsx applications that do not support X11R6 session management to participate in an X11R6 session. 

I n order for smproxy to act as a proxy for an x appl ication, one of the fol lowing must be true: 

■ Theapplication maps a top-level window containing thewM_cLiENT_LEADER property. This property provides a pointer 
to the client leader window that contains thewM_cLAss, wmjjame, wm_command, and wm_client_machine properties. 

or 

■ Theapplication maps a top-level window that does not contain thewM_cLiENT_LEADER property. H owever, this top-level 
window contains the wm_class, wmjjame, wm_command, and wm_client_machine properties. 
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An application that supports the wm_save_yourself protocol will receive a wm_save_yourself client message each time the 
session manager issues a checkpoint or shutdown. This allows the application to save state. If an application does not 
support the wm_save_yourself protocol, then the proxy will provide enough information to the session manager to restart 
the application (using wm_command), but no state will be restored. 

SEE ALSO 

xsm(l) 

AUTHOR 

Ralph M or, X Consortium 

X Version 11 Release 6 


sort 

sort— Sort lines of text files 

SYNOPSIS 

sort [-emus] [-t separator ] [-0 output-file] [ - T t e mp d i r ] [-bdfiMnr] 

[+POS1 [-POS2]] [-k POS1[,P0S2]] [file...] 
sort {--help,--version} 

DESCRIPTION 

This manual page documents the GN U version of sort, sort sorts, merges, or compares all the lines from the given files, or 
the standard input if no files are given. A filename of - means standard input. By default, sort writes the results to the 
standard output. 

sort has three modes of operation: sort (the default), merge, and check for sorted ness. The foil owing options change the 
operation mode: 

-c C heck whether the given files are already sorted; if they are not all sorted, print an error message and exitwith a 
status of 1 . 

-m M ergethegiven files by sorting them asagroup. Each input file should already be individually sorted. It always 
works to sort instead of merge; merging is provided becauseit isfaster, in the case where it works. 

A pair of lines is compared as follows: if any key fields have been specified, sort compares each pair of fields, in the order 
specified on the command line, according to the associated ordering options, until a difference is found or no fields are left. 

If any of the global options Mbdtinr are given but no key fields are specified, sort compares the entire lines according to the 
global options. 

Finally, as a last resort when all keys compare equal (or if no ordering options were specified at all), sort compares the lines 
byte by byte in machine collating sequence. The last resort comparison honors the - r global option. The -s (stable) option 
disables this last-resort comparison so that lines in which all fields compare equal are left in their original relative order. If no 
fields or global optionsarespecified, -s has no effect. 

GNU sort has no limits on input line length or restrictions on bytes all owed within lines. In addition, if the final byte of an 
inputfileisnot a newline, GNU sort silently supplies one 

If the envi ronment variable tmpdir is set, sort uses it as the directory in which to put temporary files instead of the default, 

/ tmp . The -t tempdir option is another way to select the di rectory for temporary fi les; it overrides the environment 
variable. 

The following options affect the ordering of output lines. They may be specified globally or as part of a specific key field. If 
no key fields are specified, global options apply to comparison of entire lines; otherwise, the global options are inherited by 
key fields that do not specify any special options of their own. 
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-b Ignore leading blankswhen finding sort keysin each line. 

-d Sortin phone directory order; ignore all characters except letters, digits, and blankswhen sorting. 

-f Fold lowercase characters into the equivalent uppercase characters when sorting so that, for example, b is sorted 
the same way b is. 

-i Ignore characters outsidetheASC 11 range 040-0176 octal (inclusive) when sorting. 

-m An initial string, consisting of any amount of whitespace, followed by three letters abbreviating a month name, is 

folded to uppercaseand compared in theorder 'jan' < 'feb 1 < ... < dec 1 . Invalid names compare low to 
valid names. 

-n Compare according to arithmetic value an initial numeric string consisting of optional whitespace, an optional - 
sign, and zero or more digits, optionally followed by a decimal point and zero or more digits 
-r Reverse the result of comparison, so that lines with greater key values appear earlier in the output instead of later. 


Other options are 
-o out put - f i I e 

-t separator 


-u 

+POS1 [-P0S2] 


-k POS1[,P0S2] 


W rite output to out put - f i i e instead of to the standard output. If output- f i i e is one of the input 
files, sort copies it to a temporary file before sorting and writing the output to out put - f i i e. 

Use character s e pa r at or as the field separator when finding the sort keys in each line. By default, 
fields are separated by the empty string between a nonwhitespace character and a whitespace 
character. That is to say, given the input line too bar, sort breaks it into fields too and bar. The 
field separator is not considered to be part of either the field preceding or the field following it. 

For the default case or the -m option, only output the first of a sequence of lines that compare 
equal. For the -c option, check that no pair of consecutive lines compares equal. 

Specify afield within each line to use as a sorting key. Thefield consists of the portion of theline 
starting at posi and up to (but not including) pos 2 (or to the end of the line if pos 2 is not given). 
Thefi elds and character positions are numbered starting with 0 . 

An alternate syntax for specifying sorting keys. The fields and character positions are numbered 
starting with 1 . 


A position has the form f .c, where f is the number of thefield to use and c is the number of the first character from the 
beginning of thefield (for +pos) or from the end of the previous field (for -pos).The .c part of a position may be omitted, 
in which case it is taken to be the first character in thefield. If the -b option has been given, the .c part of afield specifica¬ 
tion is counted from the first nonblank character of thefield (for +pos) or from the first nonblank character following the 
previous field (for -pos). 

A +pos or - pos argument may also have any of the option letters Mbdtinr appended to it, in which case the global ordering 
options are not used for that particular field. The - b option may be independently attached to either or both of the+pos and 
-pos parts of afield specification, and if it is inherited from the global options, it will be attached to both. If a - n or -m 
option is used, thus implying a -b option, the -b option is taken to apply to both the+pos and the - pos parts of a key 
specification. Keys may span multiple fields. 

In addition, when GNU join isinvoked with exactly one argument, thefollowing optionsare recognized: 

--help Print a usage message on standard output and exit successfully 

--version Print version information on standard output, then exit successfully 


COMPATIBILITY 

H istorical (BSD and System V) implementations of sort havediffered in their interpretation of some options, particularly 
-b, -t, and -n.GNU sort follows thePOSIX behavior, which is usually (but not always) like the System V behavior. 
According to POSIX, -n no longer implies -b. For consistency, -m has been changed in the same way. This may affect the 
meaning of character positions in field specifications in obscure cases. If this bites you, the fix is to add an explicit -b. 

BUGS 

The different meaning of field numbers depending on whether -k is used is confusing. It's all PO SIX'S fault! 

GNU Text Utilities 
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spctoppm 

spctoppm— Convert an Atari compressed Spectrum file into a portable pi xmap 

SYNOPSIS 

spctoppm [s pcfiI e ] 

DESCRIPTION 

spctoppm reads an Atari compressed Spectrum file as input and produces a portable pixmap as output. 

SEE ALSO 

sputoppm(l), ppm(5) 

AUTHOR 

Copyright® 1991 by Steve Belczyk (seb3@gte.com) andjef Poskanzer. 

19 July 1990 


split 

split— Split a file into pieces 

SYNOPSIS 

split [-lines] [-1 lines] [-b byt es [bkm] ] [-C bytes [ bkm ] ] [ --lines=l i nes ] 
[--bytes=bytes [bkm]] [- -line -bytes=b y t e s [bkm]] [--help] [--version] 
[infile [outfile-prefix]] 


DESCRIPTION 

This manual page documents the GN U version of split, split creates one or more output files (as many as necessary) 
containing consecutive sections of the intiie, or the standard input if none is given or the name- isgiven. Bydefault, 
split puts 1000 lines of the input file, or whatever is left if it is less than that, into each output file. 

The output filenamesconsist of a prefix followed by a group of letters, chosen so that concatenating the output files in sorted 
order by fi lename produces the original i nput fi le in order. The default output fi lename prefix is x. If the outf iie - prefix 
argument is given, it is used as the output fi lename prefix i nstead. 


OPTIONS 

-I i nes, -1 I i nes, --lines=l i nes 
-b bytes[bkm], --bytes=bytes [bkm] 


-C bytes[bkm], --line-bytes=bytes[bkm] 


Puti i nes lines of the input file into each output file 

Put b y t e s bytes of the input file into each output file bytes isanon-zero 

integer, optionally followed by one of the following characters to specify a 

different unit: 

b 512-byte blocks 

k 1-kilobyte blocks 

m 1-megabyte blocks 

Put into each output fi le as many complete lines of the input file as is 
possi ble without exceeding bytes bytes. If a line that is longer than bytes 
bytes occurs, put bytes bytes of it into each output file until less than bytes 
bytes of the line are left, then continue normally, bytes has the same format 
asforthe - -bytes option. 
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Print a usage message and exit with a non-zero status. 

Print version information on standard output then exit. 

GNU Text Utilities 

spottopgm 

spottopgm— Convert SPOT satellite images to portable graymap format 

SYNTAX 

spottopgm [ - 1 J 2 1 3 ] [Firstcol Firstline Lastcol Lastline] inputfile 

OPTIONS 

-11213 Extract the given color from the SPOT image. The colors are infrared, visible 

light, and ultra-violet, although I don't know which corresponds to which 
number. If the image is in color, thiswill be announced on standard error. 
The default color is i. 

Firstcol Fi rst i i ne Last col Lastline Extract the specified rectangle from the SPOT image. M ost SPOT images are 

3,000 lines long and 3,000 or more columns wide. Unfortunately, the SPOT 
format only gives the width and not the length. The width is printed on 
standard error. The default rectangle is the width of the input image by 3,000 
lines. 


--help 
--version 


DESCRIPTION 

spottopgm converts the named inputfile into portable graymap format, defaulting to the first color and the whole SPOT 
image unless specified by theoptions. 

INSTALLATION 

You must edit the source program and either define bigendian or littleendian, and fix thetypedefs for uint32t, 
uinti6t, and uint8t appropriately. 

BUGS 

Currently, spottopgm doesn't determinethe length of the input file; thiswould involve two passes over the input file. It 
defaults to 3,000 lines instead. 

spottopgm could extract a three-color image (ppm), but I didn't feel I ike making the program more complicated than it is 
now. Besides, there is no one-to-one correspondence between red, green, blue, and infra-red, visible, and ultra-violet. 

I've had only a limited number of SPOT images to play with, and therefore wouldn't guarantee that this will work on any 
other images. 

AUTHOR 

W airen T oomey (wkt@csadf a. cs. adfa. oz. au) 

SEE ALSO 

The rest of thepbmpius suite. 

sputoppm 

sputoppm— Convert an Atari uncompressed Spectrum file into a portable pixmap 
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SYNOPSIS 

sputoppm [spufiI e ] 

DESCRIPTION 

sputoppm reads an Atari uncompressed Spectrum file as input and produces a portable pixmap as output. 

SEE ALSO 

spctoppm(l), ppm(5) 

AUTHOR 

Copyright© 1991 by Steve Belczyk (seb3@gte.com) and Jef Poskanzer. 

19 July 1990 


sq 

sq— Squeeze a sorted word list 
unsq— Unsqueeze a sorted word list 

SYNOPSIS 

sq < infile > o u t f i I e 
unsq < i nfiIe > out fiI e 

DESCRIPTION 

sq compresses a sorted list ofwords (a dictionary). For example, 

sort /usr/dict/words ] sq ] compress > words.sq.Z 

will compress diet by about a factor of 4. 

unsq uncompresses the output of sq. For example, 

compress -d < words.sq.Z | unsq \ sort -f -o words 

will uncompress a dictionary compressed with sq. The squeezing is achieved by eliminating common prefixes and replacing 
them with a single character that encodes the number of characters shared with the preceding word. The prefix size is 
encoded as a single printable character: 0-9 represent 0-9, A-Z represent 10-35, and a-z represent 36-61. 

AUTHOR 

M ikeWexler 

SEE ALSO 

compress(l), sort(l). 

Local 


startx 

star-tx— Initialize an x session 

SYNOPSIS 

startx [[client ] options ..] [-- [ server ] options ... ] 



DESCRIPTION 


NOTE 


The startx script supplied with the X11 distribution is a sample designed more as a base for customization than as a fin¬ 
ished product. Site administrators are urged to customize it for their site— and to update this manual page when they do. 


T he startx script is a front end to ximt that provides a somewhat nicer user interface for running a single session of theX 
Window System. It istypically run with no arguments. 

T o determine the client to run, startx first looks for a file called .xinitrc in the user's home directory. If that is not found, 
it uses the file xinitrc in thexinit library directory. If command-line client options are given, they override this behavior. 

T o determine the server to run, startx first looks for a file called .xserverrc in the user's home directory. If that is not 
found, it uses the file xserverrc in thexinit library directory. If command-line server options are given, they override this 
behavior. U sers rarely need to provide a .xserverrc file. (Seethexinit(l) manual page for more details on the arguments.) 

The .xinitrc is typically a shell script that starts many clients according to the user's preference. When this shell script exits 
startx kills theserver and performsany other session shutdown needed. M ost of the clients started by .xinitrc should be 
run in the background. The last client should run in the foreground; when it exits, the session will exit. People often choose a 
session manager, window manager, orxterm as the "magic'' client. 

EXAMPLE 

Following is a sample xinitrc that starts several applications and leaves the window manager running as the "last" applica¬ 
tion. Assumingthatthewindow manager has been configured properly, theuserthen chooses the Exit menu item to shut 
down x. 

xrdb -load $HOME/ .Xresources 
xsetroot -solid gray & 
xbiff -geometry -430+5 & 
oclock -geometry 75x75-0-0 & 
xload -geometry -80-0 & 
xterm -geometry +0+60 -Is & 
xterm -geometry +0-100 & 
xconsole -geometry -0+0 -fn 5x7 & 
exec twm 


ENVIRONMENT VARIABLES 

display This variable gets set to the name of the display to which clients should connect. N otethat this gets set, not read. 


FILES 


$(HOME)/.xinitrc 
$(HOME)/.xserverrc 
<XRoot>/lib/X11/xinit/xinitrc 


<XRoot>/lib/X11/xinit/xserverrc 


Client to run. T ypically a shell script that runs many programs in the background. 
Server to run. T he default is x. 

Client to run if the user has no .xinitrc file. <xRoot> refers to the root of the X11 
install tree. 

Client to run if the user has no. xserverrc file. Thisis only needed if theserver 
needs special arguments or is not named. <xRoot> refers to the root of the X11 
install tree. 


SEE ALSO 

xinit(l) 


X Version 11 Release 6 
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strings 

strings— Print the strings of printable characters in files 

SYNOPSIS 

strings [ - a|-J- - all ][-f|--print-file-name][-o ][ - - help ][-v|--version ] 
[ -n min-len j-min-len |--bytes= min-len ][-t o,x,d ] 

[ --target=bf d n a me ] j--radix= o,x,d ] file 


DESCRIPTION 

Foreachf i i e given, GNU strings prints the printable character sequences that are at least four characters long (or the 
number given with the options below) and are followed by aNUL or newline character. By default, it only prints the strings 
from the initialized data sectionsof object files; for other types of files, it prints the strings from thewholefile. 

strings is mainly useful for determiningthecontentsof nontext files. 


OPTIONS 


The long and short forms of options, shown here as alternatives, are equivalent. 


-a, - - all, - 

-f, --print-file-name 
--help 

- v, - - version 

-n mi n- I en, - mi n - I e n , -bytes=mi n - I en 
-t o,x,d, --radix=o,x,d 
--target=bf d n a me 

-o 


Do not scan only the initialized data section of object files; scan thewhole 
files. 

Print the name of the file before each string. 

Print a summary of the options to strings on the standard output and exit. 
Print the version number of strings on thestandard output and exit. 

Print sequences of characters that are at least mi n-1 en characters long, instead 
of the default 4. 

Print the offset within the file before each string. The single character 
argument specifies the radix of the offset— octal, hexadecimal, or decimal. 
Specify an object codeformat other than your system's default format. (See 
objdump(l), for information on listing available formats.) 

Like -t o. 


SEE ALSO 

binutiis entry in into; The GNU Binary U tilities, Roland H. Pesch (October 1991); ar-(l), nm(l), objdump(l), raniib(l). 

COPYING 

Copyright© 1993 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this 
manual provided thecopyright notice and this permission notice are preserved on all copies. 

Permission isgranted to copy and distribute modified versionsof thismanual under the conditions for verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 

Permission isgranted to copy and distribute translations of thismanual into another language, under the above conditions 
for modified versions, except that this permission notice may be included in translations approved by the Free Software 
Foundation instead of in the original English. 


Cygn us Support, 25 ]une!993 
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strip— D iscard symbols from object files. 

SYNOPSIS 

strip [ -Fbf d n a me j --target=bf d n a me ] [ -Ibfdnamej 
--input-target=bf d n a me ] [ -Obf dname | --output-target=bf dname ] 

[-Rsect i onname |--remove-section=sect i onname ] [ -s|--strip-all ] 

[-SJ-gj--strip-debug ][-x|--discard-all ][-X|--discard-locals] 

[-v|--verbose ][-V|--version ][-V J- - help ] objfile ... 

DESCRIPTION 

GNU strip discards all symbols from the object files obj f i i e. The list of object files may include archives. At least one 
object file must be given. 

strip modifies thefilesnamed in its argument, rather than writing modified copiesunder different names. 

OPTIONS 

-F bf dname, --target=bf dname 
- -help 

-I bfdnamefdname", --input-target=bfdname 

-0 bfdname, --output-target=bf dname 
-R secti onname, - - remove-section=s ect i onname 

-s, --strip-all 
-S, -g, - -strip-debug 
-x, - -discard-all 
-X, --discard-locals 

-v, - - verbose 

-V, --version 

SEE ALSO 

binutiis entry in info; The GNU Binary U tilities, Roland H. Pesch (October 1991) 

COPYING 

Copyright® 1991 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this 
manual provided thecopyright notice and this permission notice are preserved on all copies. 

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions 
for modified versions, except that this permission notice may be included in translations approved by the Free Software 
Foundation instead of in the original English. 


T reat the original obj f i i e as a file with the object code format 
bf dname, and rewrite it in the same format. 

Show a summary of the options to strip and exit. 

T reat the original obj f i i e as a file with the object code format 
b f d n a me. 

Replaceobj file with a file in the output format bf dname. 

Remove the named section from the file. This option may be given 
more than once. N otethat using this option inappropriately may 
make the object file unusable. 

Remove all symbols 
Remove debugging symbols only. 

Remove nonglobal symbols. 

Remove compiler-generated local symbols. (T hese usually start with l 
or a period. 

V erbose output: list all object files modified. In the case of archives, 
strip -v lists all members of the archive. 

Show the version number for strip and exit. 


Cygn us Support, 5 N ovember!991 
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subst 

subst — Substitute definitions into filets) 

SYNOPSIS 

subst [ -e editor ] -f substitutions victim ... 

DESCRIPTION 

subst makes substitutions into files, in away that is suitable for customizing software to local conditions. Each vi ct i m file is 
altered according to the contents of the subst i t uti ons file 

Thesubstituti ons file contains one line per substitution. A line consists of two fields separated by one or more tabs. The 
first field is the name of the substitution, the second is the value. N either should contain the character #, and use of text- 
editor metacharacters I ike & and \ is also unwise; the name in particular is best restricted to alphanumeric. A line starting with 
# is a comment and isignored. 

In the victim files, each line on which a substitution is to be made (a target line) must be preceded by a prototype line. The 
prototype line should be delimited in such away that it will betaken as a comment by whatever program processes the file 
later. The prototype line must contain a prototype of the target line bracketed by =( )< and >( )=; everything else on the 
prototype line is ignored, subst extracts the prototype, changes all instances of substitution names bracketed by @< and >@to 
theirvalues, and then replaces the target line with the result. 

Substitutions are done using thesed(l) editor, which must be found in either the / bin or /usr/bin directories. T o specify a 
different executable, use the - e flag. 

EXAMPLE 

If the substitutions file is 

FIRST 111 
SECOND 222 

and the victim file is 

x =2; 

/* =()<y =@<FIRST>@+@<SECOND>@;>()= */ 
y =88 +99; 
z =5; 

then subst -f substitutions victim Changes victim to 
x =2; 

/* =()<y =@<FIRST>@+@<SECOND>@;>()= */ 
y = 111 + 222; 
z =5; 

FILES 

vi ct i mdi r /substtmp. new N ew version being built 
vi ct i mdi r /substtmp.old 0 Id version during renaming 

SEE ALSO 

sed(l) 

DIAGNOSTICS 

Complains and halts if it is unable to create its temporary files or if they already exist. 
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HISTORY 

W ritten at U niversity of T oronto by H enry Spencer. 

Rich $alz added the -e flagJ uly, 1991. 

BUGS 

When creating a file to besubsted, it's easy to forget to insert a dummy target line after a prototype line; if you forget, subst 
ends up deleting which ever line did in fact follow the prototype line. 

Local 


sum 

sum— C hecksum and count the blocks in a file 

SYNOPSIS 

sum [ - rs] [ - - sysv] [--help] [--version] [file...] 

DESCRIPTION 

This manual page documents the GN U version of sum. sum computes a 16-bit checksum for each named file or the standard 
input if none are given or when a file named - is given. It prints the checksum for each file along with the number of blocks 
in the file (rounded up). By default, each corresponding filename is also printed if at least two arguments are specified. W ith 
the - -sysv option, corresponding filenames are printed when there is at least one file argument. By default, the gnu sum 
computes checksums using an algorithm that is compatible with the BSD sum and prints file sizes in units of IK blocks 

OPTIONS 

- r 

-s, - -sysv 

- -help 

- - version 

GNU Text Utilities 


Use the default (BSD-compatible) algorithm. This option is included for compatibility with the System V 
sum. Unless the -s option was also given, it has no effect. 

Compute checksums using an algorithm that is compatible with the one the System V sum uses by default 
and print file sizes in units of 512-byte blocks instead of IK. 

Print a usage message and exit with a non-zero status. 

Print version information on standard output, then exit. 


SuperProbe 

SuperProbe— Probe for and identify installed video hardware 

SYNOPSIS 

SuperProbe [-verbose] [-nol6] [-excl list] [-mask10] [-order list] [-noprobe Iist ] [-bios base] 

[-no bios] [-no dac] [-no mem] [-info] 

DESCRIPTION 

SuperProbe is a program that will attempt to determine the type of video hardware installed in an EISA/ISA/V L B-bus 
system by checking for known registersin various combinations at various locations (M icroChannel and PCI machines may 
not be fully supported; many work with the use of the -no_bios option.) This is an error-prone process, especially on UNIX 
(which usually has a lot more esoteric hardware installed than M S-D OS systems do), 90 SuperProbe may likely need help 
from the user. 
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superProbe runson SVR3, SVR4, Linux, 386BSD/FreeBSD/N etBSD, M i nix-386, and M ach. It should be trivial to extend 
it to work on any other U N IX-like operating system, and even non-UN IX operating systems. All of the operating system 
(OS) dependencies are isolated to a singlefilefor each OS. 

At this time, superProbe can identify M DA, H ercules, CGA, M CGA, EGA, VGA, and an entire horde of SVGA chipsets. 
(Seethe - info option under "Options.") It can also identify several H iColor/T rue-color RAM D AC sin use on SVGA 
boards, and the amount of video memory installed (for many chipsets). It can identify 8514/A and some derivatives, but not 
XGA, or PGC (although the author intends to add those capabilities). N or can it identify other esoteric video hardware (Iike 
Targa, TIGA, or M icrofield boards). 


OPTIONS 

-verbose 
-nol 6 


-excl\l i st 


- maskl0 


-order\l i st 


-noprobe\l i st 


-bios\base 


-no_bios 

-no_dac 
-no_mem 
-info 


superProbe will be verbose and provide lots of information as it does its work. 
superProbe will not attempt to use any ports that requi re 16-bit I/O address decodi ng. T he ori gi nal ISA 
bus only specified that I/O ports be decoded to 10 bits Therefore, some old cards (including many 8-bit 
cards) will misdecode references to ports that use the upper 6 bits, and may get into funny states because 
they think that they are being addressed when they are not. It is recommended that this option be used 
initially if any 8-bit cards are present in the system. 

superProbe will not attempt to access any I/O portson the specified exclusion list. Some video cards use 
rather nonstandard I/O ports that may conflict with other cards installed in your system. By specifying to 
superProbe, a list of ports already in use, it will know that there cannot beany video cards that use those 
ports, and hence will not probe them (which could otherwise confuse your hardware). The exclusion list is 
specified as a comma-separated list of I/O ports or port ranges. A range is specified as i o w-h i gh, and is 
inclusive. The ports can be specified in decimal, in octal (numbers begin with 0 ), or hexadecimal (numbers 
begin with bx). 

Thisoption isused in combination with -exci. It tellssuperProbe that when comparing an I/O port 
under test against the exclusion list, the port address should be masked to 10 bits. This is important with 
older 8-bit cards that only do 10-bit decoding, and for some cheap 16-bit cards as well. Thisoption is 
simply a less drastic form of the -noi6 option. 

Thisoption specifies which chipsets superProbe should test, and in which order. The list parameter is a 
comma-separated list of chipset names. This list overrides the built-in default testing order. To find the list 
of acceptable names, use the - into option described later in this list. N otethat items displayed as 
"Standard video hardware” are not usable with the - order option. 

Thisoption specifies which chipsets superProbe should not test. The order of testing will either be the 
default order, or that specified with the -order option. The list parameter is a comma-separated list of 
chipset names. To find the list of acceptable names, use the - into option. Note that items displayed as 
"Standard video hardware” are not usable with the - noprobe option. 

This option specifies the base address for the graphics-hardware B10 S. By default, superProbe will 
attempt to locate the BIOS base on its own (the normal address is 0 x 00000 ). If it fails to correctly locate 
the BIOS (an error message will be printed if this occurs), the - bios option can be used to specify the 
base. 

D isallow reading of the video BIOS and assume that an EGA or later (VGA, SVGA) board ispresentas 
the primary video hardware. 

Skip probingfortheRAM D AC type when an (S)VGA isidentified. 

Skip probing for the amount of installed video memory. 

superProbe will printout a listing of all the video hardware that it knows how to identify. 


EXAMPLES 

T 0 run superProbe in itsmost basic and automated form, simply enter the following: 
SuperProbe 
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NOTE 


You may want to redirect stdout to a file when you run superPr-obe (especially if your OS does not support Virtual 
Terminalson the console). 


H owever, if you have any 8-bit cards installed, you should initially run superProbe as 
SuperProbe -verbose -no16 

(the - verbose option is included so you can see what superProbe isskipping). 

Finer granularity can be obtained with an exclusion list, for example, 

SuperProbe -verbose -excl 0x200,0x220-0x230,0x250 

will not test for any device that uses port 0 x 200 , ports 0 x 220 through 0 x 230 , inclusive, or port 0 x 250 . If you have any 8-bit 
cards installed, you should add -maskio to the list of options. 

T 0 restrict the search to Western D igital, T seng, and Cirrus chipset, run superProbe as follows: 

SuperProbe -order WD,Tseng,Cirrus 

BUGS 

Probably a lot at this point. Please report any bugs or incorrect identifications to the author. 

It is possible that superProbe can lock up your machine. Be sure to narrow the search by using the -noi 6, -exci, and - 
maskio options provided to keep superProbe from conflicting with other installed hardware. 

SEE ALSO 

Thevgadoc3.zip documentation package by Finn Thoegersen, available in theM S-D OS archives of many FTP repositories. 
Programmer'sGuidetotheEGA and VGA Cards, Second Edition, by Richard Ferraro. 

AUTHOR 

David E. W exelblat (dwex@xfree86.org) with help from David Dawes (dawes@xfree86.org) and theXFree86 development 
team. 

Version 2.2 


tac 

tac— Concatenate and printfilesin reverse 

SYNOPSIS 

tac [-br] [-s separator] [--before] [--regex] [--separator=separat or ] 

[--help] [--version] [file...] 

DESCRIPTION 

This manual page documents the GN U version of tac. tac copies each given file, or the standard input if none are given or 
when afilenameof - is encountered, to thestandard output with the order of the records reversed. The records are separated 
by instances of a string, or a newline if none is given. By default, the separator string is attached to the end of the record that 
it follows in the file. 
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OPTIONS 

-b, - - before The separator is attached to the beginning of the record that it precedes in the file. 

-r, --regex T he separator is a regular expression. 

-s string, - - separators tring U se s t r i n g as the record separator. 

- - help Print a usage message and exit with a non-zero status. 

- -version Print version information on standard output, then exit. 

GNU Text Utilities 

tail 

tail— 0 utput the last part of fi les 

SYNOPSIS 

tail [-c [ + ]N[bkm]] [-n [ + ]N] [-fqv] [ - - bytes=[ + ]N[bkm]] [--lines=[ + ]N] 

[--follow] [--quiet] [--silent] [--verbose] [--help] [--version] [file...] 

tail [{-,+}Nbcfklmqv] [file...] 

DESCRIPTION 

This manual page documents the GN U version of tail, tan prints the last part (10 lines by default) of each given file; it 
reads from standard input if no files are given or when a filename of - is encountered. If more than one file is given, it prints 
a header consisting of the file's name enclosed in ==> and <== before the output for each file 

TheGN U tan can output any amount of data, unlike the UN IX version, which uses a fixed size buffer. It has no -r option 
(print in reverse). Reversing a file is really a different job from printing the end of a file; the BSD tan can only reverse files 
that are at most as large as its buffer, which is typically 32 KB. A reliable and more versatile way to reverse fi les is theGN U 
tac command. 

OPTIONS 

tan accepts two option formats: the new one in which numbers are arguments to the option letters, and the old one in 
which a + or - and optional number precede any option letters. 

If a number (n) starts with a+, tan begins printing with the Nth item from the start of each file, instead of from the end. 

-c n, --bytes n Tail by n bytes, n isanon-zero integer, optionally followed by one of the following characters to 
specify a different unit, 
b 512-byte blocks 

k 1 -kilobyte blocks 

m 1 -megabyte blocks 

-f, - -follow Loop forever, trying to read more characters at the end of the file, on the assumption that the file 

is growing. Ignored if reading from a pipe If more than one file is given, tan prints a header 
whenever it gets output from a different file, to indicate which file that output is from. 

-l, -n n, --lines n Tail by n lines, -l is only recognized using the old option format. 

-q, - -quiet, - -silent N ever print filename headers. 

-v, --venbose Always print filename headers. 

- - help Print a usage message and exit with a non-zero status. 

--version Print version information on standard output then exit. 



GNU Text Utilities 
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talk 

talk— Talk to another user 

SYNOPSIS 

talk person [ttyname] 

DESCRIPTION 

talk isa visual communication program that copies lines from your terminal to that of another user. 

The following options are available: 

person If you wish to talk to someone on your own machine then person is just the person's login name. If you 

wish to talk to a user on another host, then person is of the form user ghost. 
tt yname If you wish to talk to a user who is logged in more than once, thett yname argument may be used to 

indicate the appropriate terminal name, wheret t yname isof the form 
11 yxx 

When first called, talk sends the message Message from TalkDaemonghis_machine.. . : 

talk: connection requested by your_name@your_machine 
talk: respond with: talk your_name@your_machine 

to the user you wish to talk to. At this point, the recipient of the message should reply by typing 

t a I k your_name@your_machi n e 

It doesn't matter from which machine the recipient replies, as long as his login name is the same. Once communication is 
established, the two parties may type simultaneously, with their output appearing in separate windows. Typing control -l 
■ l will cause the screen to be reprinted, while your erase, kin, and word kill characters will behave normally. T o exit, 
just type your interrupt character; talk then moves the cursor to the bottom of the screen and restores the terminal to its 
previous state. 

Permission to talk may be denied or granted by use of themesg i command. At the outset, talking is allowed. Certain 
commands, in particular nroff i and pr i, disallow messagesin orderto prevent messy output. 

FILES 

/etc/hosts T o find the recipient's machine 
/var/ run/utmp T o find the recipient's tty 

SEE ALSO 

mail(l), mesg(l), who(l), write(l) 

BUGS 

The version of talk 1 released with BSD 4.3 uses a protocol that is incompatible with the protocol used in the version 
released with BSD 4.2. 

HISTORY 

The talk command appeared in BSD 4.2. 


BSD 4.2, 22 April 1991 
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teal— Runsthegcai program with the date of tomorrow's day 

SYNOPSIS 

teal [ --help | --version ] j [ --shift=[ + |-] n umber ][Argument... ] 

DESCRIPTION 

teal is a program that runsgcai with a date set one day ahead (equivalent to the - -shitt=i option). All given arguments 
are passed unmodified to thegcai program. If thegcai program shall be called with a date other than tomorrow's date, this 
desired date can be selected by using the - -sh±ft=[+| -jnumber option, in which [ + | - ]n umber is the number of days the 
desired date is distant from the actual date. The - - shift option must be given before all other arguments, which are passed 
to thegcai program. An exit status of 0 means all processing is successfully done; any other value means an error has 
occurred. 

OPTIONS 

- -help 

- - version 

- -shift=[+|-]number 

ENVIRONMENT 

GCALPROG 


Print a usage message listing all available options, then exit successfully. 

Print the version number, then exit successfully. 

Define the displacement in [ + ] -]n umber days the desired date is distant from the actual date. 

T he gcalprog environment variable containsthefilename of the executable gcai program, which 
isused by teal to call gcai. T akes precedence over thefilenamegcai, which isburned-in during 
the compilation step of tcai. 


COPYRIGHT 

Copyright® 1995,1996 by Thomas Esken. This software doesn't claim completeness, correctness, or usability. On principle, 

I will not be Iiablefor any damages or losses (implicit or explicit), which result from using or handling my software. If you 
use this software, you agree without any exception to this agreement, which binds you LEGAL LY. 

tcai isfree software and distributed under the terms of the GNU General Public License; published by the F ree Software 
Foundation; version 2 or (at your option) any later version. 

Any suggestions, improvements, extensions, bug reports, donations, proposals for contract work, and so forth are welcome! If 
you likethistool, I'd appreciate a postcard from you! 

Enjoy it =6") 

AUTHOR 

T homas Esken (esken@uni-muenster'.de) 
m H agenfeld 84 
D -48147 M uenster; G ermany 
Phone: +49 251 232585 

SEE ALSO 

gcal(l) 

16 July 1996 
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telnet— U ser i nterfaceto theT el net protocol 

SYNOPSIS 

telnet [-d] [-a] [-n tracefile] [-e escapechar] [[-1 user] host [port]] 


DESCRIPTION 

The telnet command is used to communicate with another host using theT el net protocol. If telnet is invoked without the 
host argument, it enters command mode, indicated by its prompt teinet>. In thismode, itacceptsand executes the 
commandslisted below. If it isinvoked with arguments, it performs an open command with those arguments 


OPTIONS 

-d 

-a 


-n tracefile 

-1 user 

-e escape char 

host 

port 


Sets the initial value of the debug toggle to True. 

Attempt automatic login. Currently, this sends the username via the user variable of the environ 
option if supported by the remote system. The name used is that of the current user as returned 
by getiogin 2 if it agrees with the current user ID; otherwise, it is the name associated with the 
user ID. 

Opens tracefile for recording trace information. See the set tracefile command in the 
"Commands" section. 

When connecting to the remote system, if the remote system understands the environ option, then 
user will be sent to the remote system as the value for the variable user. This option impliesthe -a 
option. This option may also be used with the open command. 

Sets the initial telnet escape character to escapechar. If escape char isomitted, then there will 
be no escape character. 

Indicates the official name, an alias, or the Internet address of a remote host. 

Indicates a port number (address of an application). If a number is not specified, the default telnet 
port is used. 


Once a connection has been opened, telnet will attempt to enable the telnetlinemode option. If this fails, then telnet will 
revert to one of two input modes— either character-at-a-timeor old line-by-line, depending on what the remote system 
supports. 

When linemode is enabled, character processing is done on the local system, under the control of the remote system. When 
input editing or character echoing is to be disabled, the remote system will relay that information. The remote system will 
also relay changes to any special characters that happen on the remote system, so that they can take effect on the local system. 

In character-at-a-timemode, most text typed is immediately sent to the remote host for processing. 

In old line-by-line mode, all text is echoed locally, and (normally) only completed lines are sent to the remote host. The local 
echo character (initially "e) may be used to turn off and on thelocal echo. (Thiswould mostly beused to enter passwords 
without the password being echoed.) 

If the linemode option is enabled, or if the locaichars toggle is True (the default for old line-by-line), the user's quit, intr, 
and flush characters are trapped locally, and sent asT el net protocol sequences to the remote side. If linemode has ever been 
enabled, then the user's susp and eof are also sent as Tel net protocol sequences, and quit is sent as a telnet abort instead 
of break There are options (see toggle autofiush and toggle autosynch in the following list) that cause this action to 
flush subsequent output terminal (until the remote host acknowledges the telnet sequence) and flush previous terminal 
input (in thecase of quit and intr). 
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COMMANDS 

While connected to a remote host, telnet command mode may be entered by typing the telnet escape character (initially 
■]). W hen in command mode, thenormal terminal editing conventionsareavailable. 

The following telnet commands are available. Only enough of each command to uniquely identify it need be typed. (This 
is also true for arguments to themode, set, toggle, unset, sic, environ, and display commands.) 

close Closea telnet session and return to command mode, 

display argument... D i splays all, or some, of the set and toggle values. 

mode type type isone of several options, dependi ng on the state of the telnet session. T he remote host is 

asked for permission to go into the requested mode. If the remote host is capable of entering that 
mode the requested mode will be entered. Thet ype optionsare 
character D isable the telnet linemode option, or, if the remote side does not 

understand the linemode option, then enter character at a time mode, 
line Enable the telnet linemode option, or, if the remote side does not 

understand the linemode option, then attempt to enter old-line-by-line 
mode. 

isig -isig Attempt to enable (disable) theTRAPsiG mode of the linemode option. This 

requires that theLiNEMODE option be enabled. 

edit -edit Attempt to enable (disable) the edit mode of the linemode option. This 

requires that theLiNEMODE option be enabled. 

softtabs Attempt to enable (disable) the soft_tab mode of theLiNEMODE option. This 

requires that-softtabs theLiNEMODE option be enabled, 
utecho -litecho Attempt to enable (disable) the lit_echo mode of theLiNEMODE option. This 
requires that theLiNEMODE option be enabled. 

? Printsout help information for the mode command, 

open host Open a connection to the named host. If no port number is specified, telnet will attempt to [ -1 

user] [ -port ] contact a Tel net server at the default port. The host specification may be either a hostname (see 

hosts(5)for more information) or an Internet address specified in thedot notation (seemet(3) for 
more information). The -1 option may be used to specify the username to be passed to the remote 
system via the environ option. W hen connecting to a nonstandard port, telnet omits any 
automatic initiation of telnet options. When the port number is preceded by a minus sign, the 
initial option negotiation isdone After establishing a connection, thefilein theuser'shome 
directory is opened. Lines beginning with a# are comment lines. Blank lines are ignored. Lines that 
begin without whitespace are the start of a machine entry. The first thing on the line is the name of 
the machine that is being connected to. The rest of the line, and successive lines that begin with 
whitespace, are assumed to beteinet commands and are processed as if they had been typed in 
manually to theteinet command prompt. 

quit Close any open telnet session and exit telnet. An end-of-file (in command mode) will also closea 

session and exit. 

send arguments Sends one or more special character sequences to the remote host. The following are the arguments 

that may be specified (more than oneargument may be specified at atime): 
abort Sends the telnet abort (Abort Processes) sequence, 

ao Sends the telnet ao (Abort Output) sequence, which should cause the 

remote system to flush all output from the remote system to the user's 
terminal. 


ayt Sends the telnet ayt (AreYou There) sequence to which theremote 

system may or may not choose to respond. 

brk Sends the telnet brk (Break) sequence, which may have significance to the 

remote system. 
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ec Sends the telnet ec (Erase Character) sequence, which should cause the 

remote system to erase the last character entered. 

ei Sends the telnet el (Erase Line) sequence, which should causethe remote 

system to erasethelinecurrently being entered, 
eof Sends the telnet eof (End-of-File) sequence 

eor Sends the telnet eor (End of Record) sequence, 

escape Sends the current telnet escape character (initially '). 

ga Sends the telnet ga (Go Ahead) sequence, which likely has no significance 

to the remote system. 

getstatus If the remote side supports the telnet status command, getstatus will 

send the subnegotiation to request that the server send its current option 
status. 

ip Sends the telnet ip (Interrupt Process) sequence, which should causethe 

remote system to abort the currently running process, 
nop Sends the telnet nop (no operation) sequence, 

susp Sends the telnet susp (suspend process) sequence, 

synch Sends the telnet sYNCHsequence.Thissequencecausestheremotesystem 

to discard all previously typed (but not yet read) input. This sequence is sent 
as top urgent data (and may not work if the remote system is a BSD 4.2 
system— if it doesn't work, a lowercase r may be echoed on the terminal). 

? Prints out help information for the send command, 

set argument value, T he set command will set any one of a number of telnet variables to a specific value or to True, 
unset argument value T he special value off turns off the function associated with the variable; this is equivalent to using 
the unset command. The unset command will disable or set to False any of the specified 
functions. The values of variables may be interrogated with the display command. The variables 
that may beset or unset, but not toggled, are listed here. In addition, any of the variables for the 
toggle command may be explicitly set or unset using the set and unset commands, 
echo T his is the value (initially ~e) which, when in line-by-line mode, toggles 

between doing local echoing of entered characters (for normal processing), 
and suppressing echoing of entered characters (for entering, say, a password), 
eof If telnet is operating in linemode or old line-by-line mode, entering this 

character as thefirst character on aline will cause this character to besntto 
the remote system. The initial value of the eof character is taken to be the 
terminal'seof character. 

erase If telnet is in localchars mode (see toggle localchars, following), and if 

telnet is operating in character at a time mode, then when this character is 
typed, a telnet ec sequence (see send ec, earlier in this man page) is sent to 
the remote system. The initial value for theerase character istaken to be the 
terminal's erase character. 

escape T his is the telnet escape character (initially ~ [) which causes entry into 

telnet command mode (when connected to a remote system), 
f lushoutput If telnet is in localchars mode (see toggle localchars) and the 

fiushoutput character is typed, a telnet ao sequence is sent to the remote 
host. The initial value for the flush character istaken to be the terminal's 
flush character. 

interrupt If telnet is in localchars mode (see toggle localchars) and the interrupt 

character is typed, a telnet iup sequence is sent to the remote host. T he 
initial value for the interrupt character istaken to betheterminal'smtr 
character. 
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kill If telnet is ifl localchars mode (see toggle localchars), and if telnet is 

operating in character at a time mode, then when thischaracter is typed, a 
telnet el sequence is sent to the remote system. The initial value for the 
kill character is taken to be the terminal's km character, 
inext If telnet isoperating in linemode or old line-by-line mode, then this 

character is taken to be the terminal's inext character. The initial value for 
the inext character istaken to be the terminal's inext character, 
quit If telnet is in localchars mode (see toggle localchars) and the quit 

character is typed, a telnet brk sequence is sent to the remote host. T he 
initial value for the quit character istaken to be the terminal's quit 
character. 

reprint If telnet isoperating in linemode or old line-by-line mode, then this 

character istaken to be the terminal's reprint character. The initial value for 
the reprint character istaken to be the terminal's reprint character, 
start If theTELNETTOGGLE-FLow-coNTROL option hasbeen enabled, then this 

character istaken to be the terminal's start character. The initial value for 
the start character istaken to be the terminal's start character, 
stop If theTELNETTOGGLE-FLow-coNTROL option hasbeen enabled, then this 

character istaken to be the terminal's stop character. The initial value forthe 
kill character istaken to be the terminal's stop character, 
susp If telnet is in localchars mode, or linemode is enabled, and thesuspend 

character is typed, a telnet susp sequence is sent to the remote host. The 
initial value for the suspend character istaken to betheterminal'ssuspend 
character. 

tracefiie This is the file to which the output, caused by netdata or option tracing 

being True, will be written. Ifitissetto -, then tracing information will be 
written to standard output (the default). 

worderase If telnet isoperating in linemode or old line-by-line mode, then this 

character istaken to betheterminal'sworderase character. The initial value 
fortheworderase character istaken to betheterminal'sworderase 
character. 

? Di splays the set unset commands. 

sic state The sic command (Set Local Characters) is used to set or change the state of the special characters 

when the telnetlinemode option has been enabled. Special characters are characters that get 
mapped to telnet command sequences (like ip or quit) or line-editing characters (like erase and 
kill). By default, the local special characters are exported. The variables are 
export Switch to the local defaults for the special characters. The local default 

characters are those of the local terminal at thetimeteinet was started, 
import Switch to the remote defaults for the special characters. The remote default 

characters are those of the remote system atthetimewhen theteinet 
connection was established. 

check Verify the current settings for the current special characters. The remote side 

is requested to send all the current special character settings, and if there are 
any discrepancies with the local side, the local side will switch to the remote 
value. 

? Prints out help information for the sic command. 
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environ arguments... Theenviron command is used to manipulate the vari ables that may besentthrough the telnet 
environ option. The initial set of variables is taken from the users environment, with only the 
display and printer variables being exported by default. The user vari able is also exported if the 
-a or -l options are used. 

Valid arguments for the environ command are 

define variable value D efi ne the variable vari abi e to have a value of v a i ue. Any variables 
defined by thiscommand are automatically exported. The value may 
be enclosed in single or double quotes so that tabs and spaces may be 
included. 

undefine variable Remove v a r i a bi e from the list of environment variables, 

export variable M ark the variable vari a bi e to be exported to the remote side, 

unexport variable M ark the variable v a r i abi e to not be exported unless explicitly asked 

for by the remote side. 

list List the current set of environment variables. Those marked with a* 

will be sent automatically; other variables will only be sent if explicitly 
requested. 

? Prints out help information for the environ command, 

toggle arguments. .. T oggle (between True and False ) various flags that control how telnet responds to a/ents. These 
flags may beset explicitly to True or False using the set and unset commands listed earlier. M ore 
than one argument may be specified. The state of these flags may be interrogated with the display 
command. Valid arguments are 

autofiush If autofiush and locaichars are both t rue, then when the ao or 

quit characters are recognized (and transformed into telnet 
sequences; see set for details), telnet refuses to display any data on 
the user's terminal until the remote system acknowledges (via a 
telnet timing mark option) that it has processed those telnet 
sequences. The initial value for this toggle is True if the terminal user 
had notdonean "stty nofish''; otherwise, False. (Seestty(l) for 
more details.) 

autosynch If autosynch and locaichars are both True, then when either the 

intr or quit character is typed (see set for descriptions of the intr 
and quit characters), the resulting telnet sequence sent isfollowed by 
the telnet synch sequence. This procedure should cause the remote 
system to begin throwing away all previously typed input until both 
of the telnet sequences have been read and acted upon. The initial 
value of this toggle is False. 

binary E nable or disable the telnet binary option on both input and 

output. 

inbinary E nable or disable the telnet binary option on input, 

outbinary E nable or disable the telnet binary option on output, 

crif If this is True, then carriage returns will besent as<cR><LF>. If this is 

False, then carriage returns will besent as <cr><nul>. The initial 
value for thistoggle is False. 

crmod T oggle carriage return mode. When this mode is enabled, most 

carriage return characters received from the remote host will be 
mapped into a carriage return followed byaline feed.This mode does 
not affect those characters typed by the user, only those received from 
the remote host. T his mode is not very useful unless the remote host 
only sends carriage return, but never linefeed. The initial value for 
this toggle is False. 



512 


Parti: User Commands 


Z 

! c o mma n d 

status 

? c o mma n d 


debug 

localchars 


netdata 

options 


T oggles socket level debuggi ng (useful only to the super user). T he 
initial value for thistoggle iSFalse. 

If this is True, then the flush, interrupt, quit, erase, and kill 
characters (see set) are recognized locally, and transformed into 
(hopefully) appropriate telnet control sequences (respectively ao, ip, 
brk, ec, and ei ; see send). The initial value for this toggle is True in 
old line-by-line mode, and False in character at a time mode. When 
the linemode option is enabled, the value of localchars is ignored, 
and assumed to always be True. If linemode has ever been enabled, 
then quit is sent as abort, and eof and suspend are sent as eof and 
susp; See send. 

T oggles the display of all network data (in hexadecimal format). The 
initial value for thistoggle is False. 

T oggles the display of some internal telnet protocol processing 
(having to do with telnet options). The initial value for this toggle is 
False. 


prettydump W hen the netdata toggle is enabled, ifprettydump is enabled, the 

output from the netdata command will be formatted in a more user- 
readable format. Spaces are put between each character in the output, 
and the beginning of any telnet escape sequence is preceded by an * 
to aid in locating them. 

? D isplaysthe legal toggle commands. 

Suspend telnet. This command only works when the user is using the csh(l). 

Execute a single command in a subshell on thelocal system. If command isomitted, then an 
interactive subshell is invoked. 


Show the current status of telnet. This includes the peer one is connected to, as well as the current 
mode. 


Get help. With no arguments, telnet prints a help summary. If a command is specified, telnet 
will print the help information for just that command. 


ENVIRONMENT 

telnet uses at least the home, shell, display, and term environment variables. Other environment variables may be 
propagated to the other side via the telnet environ option. 


FILES 

-/ .teinetnc U ser customized telnet startup values 

HISTORY 

T he telnet command appeared in BSD 4.2. 


NOTES 

On some remote systems, echo has to be turned off manually when in old line-by-linemode. 

In old line-by-line mode or linemode, the terminal's eof character is only recognized (and sent to the remote system) when it 
isthe first character on aline. 


BSD 4.2, 27July 1991 
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tfmtodit 

tfmtodit— C reate font files for use with groff -Tdvi 

SYNOPSIS 

tfmtodit [ -sv ][ -ggf file ][-kskewchar ] tfm file map file font 

DESCRIPTION 

tfmtodit createsafont file for use with groff -Tdvi. tfm_fiie is the name of the font metric file for thefont. map_fiie isa 
file giving the groff names for characters in thefont; this file should consist of a sequence of lines of the form: 
n c1c2 ... 

where n is a decimal integer giving the position of the character in thefont, and ci, c 2 , ... are the groff names of the 
character. If a character has no groff names but exists in the tfm file then it will be put in the groff font file as an unnamed 
character, font isthe name of the groff font file. The groff font fileiswritten to font. 

The -s option should be given if thefont is special (a font is special if troff should search it whenever a character is not 
found in the current font.) If thefont is special, it should be listed in the fonts command in theDEsc file; if it is not special, 
there isno need to list it becausetroff can automatically mount it when it’sfirst used. 

To do a good job of math typesetting, groff requires font metric information not present in the tfm file. The reason for this 
is that has separate math italic fonts whereas groff uses normal italic fonts for math. The additional information required by 
groff is given by the two arguments to themath_fit macro in the M etafont programs for the Computer M odern fonts. In a 
text font (a font for which math_fittmg is False), M etafont normally ignores these two arguments M etafont can be made 
to put this information in thegf file by loading the following definition after cmbase when creating cm. base: 

def ignore_math_fit (expr left_ad just merit, right_adjustment) = 

special "adjustment"; 

numspecial left_adjustment*16/designsize; 

numspecial right_adjustment*16/designsize; 

enddef; 

Thegf file created usingthismodified cm.base should be specified with the -g option. The -g option should not be given 
for a font for which math_fitting istrue. 

OPTIONS 

-V 
-S 

-kn 

- gg f _f i I e 

FILES 

/ usr / lib /g rof f /font /devdvi/DEsc D evice description file. 

/usr/iib/groff/font/devdvi/F Font description file for font F . 

SEE ALSO 

groff(l), grodvi(l), groff_font(5) 


Print the version number. 

Thefont is special. The effect of this option is to add the special command to thefont file. 
Theskewchar of this font is at position n. n should bean integer; it may be given in decimal, or with a 
leading 0 in octal, or with a leading @x in hexadecimal. The effect of this option is to ignore any kerns 
whose second component isthe specified character. 

gf f i 1 e isa gf file produced by M etafont containing special and numspecial commands giving additional 
font metric information. 


Groff Version 1.09,14 February 1994 
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tftp 

tttp—Trivial file transfer program 

SYNOPSIS 

tftp [host ] 


DESCRIPTION 

tttp is the user interface to the Internet tftp (Trivial FileT ransfer Protocol), which allows users to transfer files to and from 
a remote machine. The remote host may be specified on the command line, in which case tftp uses host as the default host 
for future transfers. (See the connect command in the following section.) 


COMMANDS 

Oncetftp isrunning, it issues the prompt: 

tftp> 


and recognizes the following commands: 


? c o mma n d - n a me ... 

ascii 

binary 

connect host-name port 


get filename, 

get remotename localname, 

get filel file2 ... f i I e N 

mode transfer -mode 
put file 

put localfile remotefile 
put filel f i I e 2 ... 
fileN remote-directory 


quit 

rexmt 

retransmission-timeout 

status 

timeout 

total - transmi ssi on-ti me out 

trace 

verbose 


Print help information. 

Shorthand for "mode ascii" 

Shorthand for "mode binary” 

Set the host (and optionally port ) for transfers. N ote that theT FTP protocol, uni ike the 
FTP protocol, does not maintain connections between transfers; thus, the connect 
command does not actually create a connection, but merely remembers what host is to be 
used for transfers. You do not have to use the connect command; the remote host can be 
specified as part of the get or put commands. 

Get a file or set of files from the specified sources. Source can be in one of two forms: a 
filename on the remote host, if the host has already been specified; or a string of the form 
hosts:filenameto specify both a host and filename at the same time If the latter form is 
used, the last hostname specified becomes the default for future transfers. 

Set the mode for transfers; transfer-mode may be ascii or binary. T he default is ascii. 
Put a file or set of files to the specified remote file or directory. The destination can be 
in one of two forms: a filename on the remote host, if the host has already been specified; 
or a string of the form hosts: filename to specify both a host and filename at the same 
time. If the latterform isused, the hostname specified becomes the default for future 
transfers. If the remote-directory form isused, the remote host is assumed to bea 
UNIX machine. 

Exit tttp. An end-of-filealso exits. 

Set theper-packet retransmission time-out, in seconds. 

Show current status. 

Set the total transmission time-out, in seconds. 

Toggle packet tracing. 

T oggle verbose mode. 


BUGS 

Becausethereisno user-login or validation within theT FTP protocol, the remote site will probably have some sort of file- 
access restrictions in place. The exact methods are specific to each site and therefore difficult to document here. 
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HISTORY 

The tftp command appeared in BSD 4.3. 


BSD 4.3, 22 April 1991 


tgatoppm 

tgatoppm— Convert Truevision T arga file into a portable pi xmap 

SYNOPSIS 

tgatoppm [-debug][tgaf i I e ] 

DESCRIPTION 

Reads a T rueVision T arga file as input. Produces a portable pixmap as output. 

OPTIONS 

-debug C auses the header information to be dumped to stderr 
All flags can be abbreviated to their shortest unique prefix. 

BUGS 

Should really be in pnm, not ppm. 

SEE ALSO 

ppmtotga(l), ppm(5) 

AUTHOR 

Partially based on tga 2 rast, version 1.0, by Ian J. M acPhedran 
Copyright© 1989 byjef Poskanzer. 

26 August 1989 


tifftopnm 

tifftopnm— C onvert a TIFF file into a portable anymap 

SYNOPSIS 

tifftopnm [-headerdump] tifffile 

DESCRIPTION 

tifftopnm reads a TIF F file as input and produces a portable anymap as output. The type of the output file depends on the 
input file; if it's black and white, a pbm file is written;, if it's grayscale, a pgm file; otherwise, a ppm file. The program tel Is you 
which type it iswriting. 

OPTIONS 

-headerdump D umpTIFF file information to stderr. This information may be useful in debugging TIFF file 
conversion problems. 


All flags can be abbreviated to their shortest unique prefix. 
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SEE ALSO 

pnmtotiff(l), pnm(5) 

BUGS 

This program is not self-contained. To use it you must fetch the TIF F Software package listed in the other, systems file and 
configure pbmpius to useiibtift. Seethepbmpius Makefile for details on this configuration. 

AUTHOR 

Derived byjef Poskanzerfrom tif 2 ras.c, which is copyright® 1990 by Sun M icrosystems, Inc. Author Patrick J. Naughton 
(naughton@wind. sun. com). 

13 January 1991 

tin, rtin, cdtin, tind 

tin, rtin, cdtin, tind—A N etnews reader 

SYNOPSIS 

tin/rtin/cdtin/tind [ options ][newsgroups ] 

DESCRIPTION 

tin is a full-screen easy-to-use N etnews reader. It can read news locally (/usr/ spool/ news) or remotely (rtin or tin -r 
option) via an N NTP (Network N ews Transport Protocol) server, cdtin can read news locally and news archived on CD- 
ROM . It will automatically uti Iizenov (newsoverview)-style index files if available locally or via the nntp xover command. 

tin has five separate levels of operation: group selection level, spooidir selection level, group level, thread level and article 
level. Use then (help) command to view a list of the commands available at a particular level. 

On startup, tin will show a list of the newsgroups found in $HOME/.newsrc. An arrow -> or highlighted bar will point to the 
first newsgroup. M oveto a group by using the terminal arrow keys (terminal-dependent) or j and k. UsePgU p/PgD n 
(terminal-dependent) or Ctrl-U and Ctrl-D to pageup/down. Enter a newsgroup by pressing Return. 

TheT ab key advances to the next newsgroup with unread articles and enters it. 

OPTIONS 

-c Create/update index files for every group in $HOME/.newsrc or file specified by -t option and mark all 

articles as read. 

-f file Use the specified file of subscribed to newsgroupsin place of $HOME/.newsrc. 

- h Help listing all command-line options. 

-h Brief introduction to tin that is also shown the first time it isstarted. 

-i di r D i rectory in which to store newsgroup index files. Default is$HOME/. tin/.index. 

-m dir M ailbox directory to use. Default is$HOME/Maii. 

-m user M ail unread articles to specified user for later reading. For more information read the "Automatic M ailing 

and Saving N ew N ews” section later in thismanual page. 

-n Only load groups from the active file that are also subscribed to in the users .newsr-c. This allows a 

noticeable speedup when connecting via a slow line. 

-p program Print program with options. 

-q Quick start without checking for new newsgroups. 

-p Purge group index files of articles that no longer exist. Care should betaken when using this command as 

it starts each and every article in each group that is accessed. On a low-speed connection, this can have an 
undesirable effect and it also knocksthehell out of your filesystem. 
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-r Read news remotely from the default N NTP server specified in the environment variable nntpserver or 

Contained in thefile /etc/nntpserver. 

-r Read news saved by -s option (not yet implemented). 

-s dir Save articles to directory. Default is$HOME/News. 

-s Save unread articles for later reading by -r option. For more information, see "Automatic M ailing and 

Saving N ew N ews.” 

-u Create/update index files for every group in $HOME/.newsrc or file specified by -t option. This option is 

disabled if tin retrieves its index files via an N NTP server. 

-u Start tin in the background to update index files while reading news in the foreground. This option is 

disabled if tin retrieves its index files via an N NTP server. 

-v Verbose mode for -c, -m, -s, -u,and -z options. 

-w Quick mode to post an article and then exit. 

-z Only start tin if there is any new/unread news. If there is news, tin will position cursor at first group with 

unread news. Useful for putting in login file. 

-z Check if there is any new/unread news and exit with appropriate status. If -v option is specified, the 

number of unread articles in each group is printed. An exit code 0 indicates no news, 1 that an error 
occurred, and 2 that new/unread news exists. U seful for writing scripts. 

tin can also dynamically change its options by the m menu command. Any changes are written to $HOME/.tin/tinrc. 

The index daemon version, tind, only supportsthe-f, -h, -i,and -voptions. 

INDEX FILES 

In order to keep track of threads, tin maintains an index for each newsgroup. There are a number of methods in which 
index files can be created and updated. 

The simplest method is that each user create^updates his or her own index files that are stored in $home/. tin/ .index. This 
has the advantage that any user can compile and install tin, but the disadvantage is that each user is going to be creating 
duplicate files and using precious disk space. A good way to keep index files updated is by doing a tin -u that will update 
index files in the background while you are reading news in the foreground. You can also update index files via the system 
batcher cron with the -u option: 30 6 ***/usr/local/bin/tin -u. 

A slightly better method is to set tin setuid news and have all index files created and updated in the news spool directory 
(that is, /usr/spool/news/.index). This has the advantage that there will only be one copy of the index files on each 
machine on your network, but the disadvantage is that you will have tin running setuid news. 

A better method isto install thetind index fileupdating daemon and have it create and updateindex files for all groupsin 
your active file at regular intervals in the news spool directory (/usr/ spool /news /.index). This has the advantage that there 
will only be one copy of the index files on each machine on your network, and tin must not be setuid news, but the 
disadvantage is that you will have to have news permissions to install tind and root permissions to install an entry in the 
cron batcher system to havetind regularly update index files. 

The best method isto install thetind index fileupdating daemon on your N N TP server and have it create and updateindex 
files for all groupsin your active file at regular intervals in the news spool directory (/usr/spool/news/ .index). This has the 
advantage that there will only be one copy of the index files on the N NTP server for the whole of your network, but the 
disadvantage isthat you will have to install myNNTP server patches to allow tin to retrieveindexfilefromyourNNTP 
server and you must install an entry in the cron batcher system to havetind regularly update index files. (This is the method 
we use on our network of 40 to 50 machines and we have not had any problems.) 

Entering a group the first time tends to be slow because the index file must be built from scratch unless the tind update 
daemon is being used. T 0 alleviate the slowness, start tin to create all index files for the groups you subscribe to with 
tin -u -v and go for acoffee. Subsequent readings of agroup will cause incremental updating of the index file. 
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If reading news remotely and locally updating index files operation will be somewhat slower because the articles must be 
retrieved from the N NT P server. 

NEWSADMINIST RATION 

M aintaining Netnewson large networks of machines can be a pretty time-consuming job, asl discovered when I was given 
thejob of maintaining our news system and news users. 

tin is a N ews User Agent and so most of the users were always asking questions or doing things that could be frowned upon 
by their departments. T o relieve news administrators (and especially me) of this, features have been added to make life easier 
for them. 

When a user starts tin, it is possible to inform them of any important changes or information concerning the news system by 
displaying a message of the day (motd) file. The motd file should be created in your news lib directory (/usr/ lib/news /motd) 
and should have file permissions set to 0644 . The motd file will only be displayed if its contents is newer than the last time 
the user started tin. If reading news via N NTP, my xmotd patch will have to have been applied to yourNNTP server. 

A user starting tin for the first time can be automatically subscribed to a list of newsgroups that are deemed appropriate by 
the news administrator. At our site the subscriptionsfile has 125 groups (our active file contains more than 400 groups with 
many only being marginally interesting to most people). The subscriptions file should be created in your news lib directory 
(/usr/lib/news/subscriptions) and should have file permissions set to 0644 . If reading news via N NTP, my list 
subscriptions patch will have to have been applied to your N NTP server. 

If my N NTP xuser patch has been applied to your N NTP server, you will be able to log the username and machine to your 
NNTP logfilefor usage statistics 

SCREEN FORMAT 

tin has five separate levels of operation: group selection level, spooidir selection level, group level, thread level, and article 
level. 

At the group selection level, the title displays the number of subscribed groups. The newsgroups are displayed on the left of 
thescreen with thenumber of unread articles displayed on thesamelinein themiddleof thescreen, likethis: 

Selection Num><Newsgroup><Num of unread articles> 
i.e., 

1 alt.sources 10 

2 comp.sources.misc 3 

3 news.software.readers 12 

At the group level, the title contains the name of the group, thenumber of conversation threads, and total number of articles, 
for example, ait. sources (7 23 ). If the group has been setup not to thread articles (for example, ait. sources is in 
$ ( home) / .tin/unthread), the title will be ait. sources <u 23 ). There aretwo possible display formats: 

Selection Num><Unread><Responses><Subject><Author> 
e.g., 

1 + 3 Bnews sources? iain@anl433.uucp 

2 1 This question has ether@net 

or 

Selection Num><Unread><Responses><Subject (longer)> 
e.g., 

1 + 3 Bnews sources? 

2 1 This question has a longer subject line 

At the article level, the page header has the following format: 

<Date posted><Newsgroup> 

<Thread 1 of n> 

<Article Num><Subject><Num of responses in thread> 
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<Author><Organization> 

<Article body> 
i.e., 

24 Jul 15:20:03 GMT alt.sources Thread 1 of 2 

Article 452 Bnews sources? 3 responses 

iain@anl433.uucp Organization name 

COMMON MOVING KEYS 

The following table shows the common keys/commands for moving at all five levels within tin: 

Beginning of list/article Home i ("r or g at article level) 

End of list/article End $ (also Gat article level) 

Pageup PgUp ‘u or 'b or b 

Page down PgDn 'Dor 'For<sPACE> 

Lineup up arrow k (not at article level) 

Linedown Down arrow j (not at article level) 

COMMON EDITING COMMANDS 

An emacs -style editing package allows the easy editing of input strings. A history list allows the easy reuse of previously 
entered strings. T he following commands are availablewhen editing a string: 

"A, a e M oveto beginning or end of line, respectively. 

~f, a b N ondestructive move forward or back one location, respectively. 

a d Delete the character currently under the cursor, or send eof if no characters are in the buffer. 

a h, <del> D elete character left of the cursor. 

a k Delete from cursor to end of line 

a p, -n M ove through history, previous and next, respectively. 

a l, a r Redraw the current line 

<cr> Places line on history list if nonblank, appends newline, and returns to the caller. 

<esc> Abortsthe present editing operation. 

NEWSGROUP SELECTION COMMANDS 

4 Select group 4. 

•k D elete current group from $HOME/,newsrc file. 

a l Redraw page. 

A R Reset $HOME/.newsrc file. 

<cr> Read current group. 

<tab> View next group with unread news. Will wrap around to the beginning of the group selection list looking 

for unread groups. 

b M ail a bug report or comment to the author. This is the best way to get bugs fixed and features added/ 

changed. 

c M ark current group as all read with confirmation and go to next group in group selection list, 

c M ark current group as all read and go to next unread group in group selection list, 

d T oggle display to show just the group name or the group nameand the group's description, 

g Choose a new group by name. The position of the group within the group list will also be asked for. When 

i is entered, the new group will be the first group in the displayed list; when 8 is entered, the group will be 
the eighth group in the list; and so on. When $ is entered, the group will be the last group displayed. 
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h H elp screen of newsgroup selection commands. 

h T oggle the display of help mini-menu at the bottom of the screen, 

i Toggle inverse video. 

1 List and allow selection of the available spool directories. This feature requires a special library to be linked 

with tin to create ccitin, which can then read news from an active news feed and also from multiple C D - 
ROMs. 

m M ovethecurrent group within thegroup selection list. W hen i isentered, thegroup will become the first 

displayed group in the list; when s isentered, the eighth group in the list; and so on. W hen $ isentered, 
thegroup will be the last group displayed. 

m User-configurable 0 ptionsmenu (for more information, see the "Global Options M enu” section later in 

thismanual page), 
q Quit tin. 

Q Quit tin. 

r T oggle display of all subscribed-to groups and just the subscribed-to groups containing unread articles. 

Command has no effect if groups were read from the command line when tin was started, 
s Subscribe to current group, 

s Subscribe to groups matching user-specified pattern, 

u U nsubscri be to current group, 

u U nsubscri be to groups matching user-specified pattern, 

v Print tin version information, 

w Post an article to current group. 

w List articles posted by user. The date posted, the newsgroup, and the subject are listed, 

y Thefirsttimethiscommand iscalled, itwill yank in ail groups from $LiB-DiR/activethatarenotin 

$HOME/.newsrc. 

After any groups have been subscribed/unsubscribed to, thiscommand, if pressed again, will reread $home/ 
.newsrc and display only the subscribed groups. 
y Reread the active file to seeifanynew newshasarrivedsincestartingtin. 

z Markall articles in the current group as unread, 

z U ndeletepreviously deleted group by 'k command from $home/. newsrc. 

/ Group forward search. 

? G roup backward search. 

SPOOL DIRECTORY SELECTION COMMANDS 

4 Select spool directory 4. 

a l Redraw page. 

<cr> Read news from selected spool directory. 

b M ail a bug report or comment to the author. This isthe best way to get bugs fixed and features 

added/changed. 

h Helpscreen of spool directory selection commands. 

h T oggle the display of help mini-menu at the bottom of the screen, 

i Toggle inverse video, 

q Return to previous level. 

q Quit tin. 

v Print tin version information. 
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GROUP INDEX COMMANDS 

4 Select article 4. 

"K Kill current article (for more information, see the "Automatic Kill and Selection” section later in this 

manual page). 

"L Redraw page. 

<cr> Read current article. 

<tab> View next unread article or group, 

a Author forward search. 

a Author backward search, 

c M ark all articles as read with confirmation, 

c M ark all articles as read and go to next group with unread news, 

d T oggle display to show just the subject or the subject and author, 

g Choose a new group by name, 

h Help screen of group index commands. 

h T oggle the display of help mini-menu at the bottom of the screen, 

i Toggle inverse video. 

k M ark articl^thread as read and advance to next unread articl^thread. 

i List the author of each response in current thread and enter thread selection level, 

m M ail current articl^thread/auto-selected (hot) article^articles matching pattern/tagged articles to someone. 

m User-configurable 0 ptionsmenu (for more information see "Global Options M enu" section), 

n Go to next group. 

n G o to next unread article. 

o Output current arti cl ^th read/ autosel ected (hot) article^articles matching pattern/tagged articles to 

printer. 

p Go to previous group, 

p Go to previous unread article, 

q Return to previous level. 

Q Quittin. 

s Save current arti cl^th read/autosel ected (hot) articled articles matching pattern/tagged articles to fil^file^ 

mailbox. T o save to a mailbox, enter = or =maiibox when asked for filename to save to. T o save in 
cnewsgroup name>/<fiiename> format, enter +fiiename. E nvironment variables are allowed within a 
filename (for example $SOURCES/dir/filename). 

t Tag current articl^thread for mailing (m)/piping (|)/printing (o)/saving (s)/crossposting (x). 

u Toggle display to show all articles as unthreaded or threaded, 

u U ntag all articles that were tagged, 

v Print tin version information, 

w Post an article to current group. 

w List articles posted by user. The date posted, the newsgroup, and the subject are listed, 

x C rosspost already posted current articl^thread/autoselected (hot) articles/articles matching pattern/tagged 

articles to another newsgroup(s). Useful for reposting from global to local newsgroups, 
x M ark all unread articles that have not been selected as read, redo screen to reflect changes, and put index at 

the first thread to begin reading. Pressing x again will toggle back to theway it was before See • command 
f o r cl eari n g th e toggl e effect, 
z M ark current article as unread, 

z M ark current thread as unread. 
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Search forward for specified subject. 

Search backward for specified subject. 

Show last message. 

Pipe current article/thread/autoselected (hot) articles/articles matching pattern/tagged articles i nto 
command. 

Select current thread for later processing. 

Toggle selection of current thread. If at least one unread art in thread (but not all unread arts) is selected, 
then all unread arts become selected. 

Reverse all selections on all articles. 

U ndo all selections on all articles. It clears the toggle effect of x command. Thus, after first doing an x, you 
can then do • to reset articles. Thus, you can iteratively whittle down uninteresting threads. 

Perform autoselection on current group. 

For each thread in current group, if it at least one unread art is selected, all unread arts become selected. 

T his is useful for auto selection on author when the reader wants to see theenti re thread. 

Prompts for a pattern with which to match on. All threads whose subjects match the pattern will be 
selected. A pattern of * will match all subjects. Entering just <cr> will cause the previous pattern to be 
used. 

THREAD LISTING COMMANDS 

4 Select article 4 within thread. 

-l Redraw page. 

<cr> Read current articlewithin thread. 

<tab> View next unread articlewithin thread. 

b M ail a bug report or comment to the author. T his is the best way of getting bugs fixed and features added/ 

changed. 

c M ark thread as read after confirmation and return to previous level, 

d Toggle display to show just the subject or the subject and author, 

h H elp screen of thread listing commands. 

h T oggle the display of help mini-menu at the bottom of the screen, 

i Toggle inverse video. 

k M ark thread as read and return to previous level, 

q Return to previous level. 

Q Quittin. 

r Toggle display to show all articles or only unread articles. 

b M ail a bug report or comment to the author. This is the best way of getting bugs fixed and features added/ 

changed. 

t Tag current article for mailing (m)/piping (|)/printing (o)/saving (s)/crossposting (x). 

t Return to group index level, 

v Print tin version information, 

z M ark current articlein thread asunread. 

z M ark all articles in thread asunread. 

ARTICLE VIEWER COMMANDS 

0 Read the base article in thisthread. 

4 Read response4 in thisthread. 

-h Show all of the article's mail header. 
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Kill current article (for more information, see the "Automatic Kill and Selection'' section) 

Redraw page. 

Go to next base article 
Go to next unread article. 

Author forward search. 

Author backward search. 

M ark all articles as read with confirmation and return to group selection level. 

M ark current group as all read and go to next unread group in group selection list. 

T oggle rot-13 decodi ng for this article 

Delete current article. It must have been posted by the same user. The cancel message can be seen in the 
newsgroup control. 

Post a follow-up to the current article with a copy of the article included. 

Post a follow-up to the current article. 

H elp screen of article page commands. 

T oggle the display of help mini-menu at the bottom of the screen. 

T oggle inverse video. 

M ark article as read and advance to next unread article 
M ark thread as read and advance to next unread thread. 

M ail current articl^thread/autoselected (hot) articles/articles matching pattern/tagged articles to someone. 
User-configurable Options menu (for more information, see the "G lobal OptionsM enu” section later in 
this manual page). 

Go to the next article. 

Go to the next unread article 

Output current arti cl ^th read/ autosel ected (hot) articled articles matching pattern/tagged articles to 
printer. 

Output article/thread/tagged articles to printer. 

Go to the previous article. 

Go to the previous unread article. 

Return to previous level. 

Quit tin. 

Reply through mail to the author of the current article with a copy of the article included. 

Reply through mai I to the author of the current article. 

Save current arti cle/th read/autosel ected (hot) articled articles matching pattern/tagged articles to fil^file^ 
mailbox. T o save to a mailbox enter = or =maiibox when asked for filename to save to. T o save in 
<newsgroup name>/<tiiename> format, enter +tiiename. E nvironment variables are allowed within a 
filename (such aS$SOURCES/dir/filename). 

Return to group selection level. 

T ag current article for mailing (m)/piping (\ (/printing (o)/saving (s)/crossposting (x). 

Print tin version information. 

Post an article to current group. 

List articles posted by user. The date posted, the newsgroup and the subject are listed. 

C rosspost already posted current articl^thread/autosel ected (hot) articled articles matching pattern/tagged 
articles to another newsgroup(s). U seful for reposting from global to local newsgroups. 

M ark article as unread. 

Article forward search. 

Article backward search 
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Pipe current article/thread/autoselected (hot) articles/articles matching pattern/tagged articles into 
command. 

Go to the first article in the current thread. 

Go to the last article in the current thread. 

Select current thread for later processing. 

Toggle selection of current article. 

R everse arti cl e sel ecti on s. 

Undo all selections on current thread. 


GLOBALOPTIONSMENU 


This menu is accessed by pressing m at all levels. It allows the user to customize the behavior of tin. The options are saved to 
thefile$HOME/.tin/tinrc. U se <space> to toggle the requi red option and <cr> to set. 


Auto save 

Editor offset 

M ark saved read 
Confirm Command 

D raw arrow 
Print header 

Go to 1st unread 

Scroll full page 
Catch up on quit 

Thread articles 


Show only unread 
Show description 

Show Author 


Process type 


Automatically save articles/threads by "Archive-name:" line in article header and post process them 
if process typeisnot set to None. 

Set on if the editor used for posting, follow-ups and bug reports has the capability of starting and 

positioning the cursor at a specified linewithin afile 

Allows saved articles'threadsto be automatically marked as read. 

Allows certain commands(such asc catchup) that require user confirmation to be executed 
immediately if set off. 

Allows groups/articles to be selected by an arrow -> if set on or by a highlighted bar if set off. 

This allows the complete mail header or only the "Subject:" and "From:" fields to be output when 
printing articles. 

This allows the cursor to beplaced atthefirst/last unread article upon entering a newsgroup with 
unread news. 

If set on, scrolling of groupsarticles will be a full page at a time; otherwise, half a page at a time 
If set on, the user is asked when quitting if all groups read during the current session should be 
marked read. 

If set on, articles will be threaded in all groups (default); otherwise, articles will be shown 
unthreaded. Threading or unthreading is possible on a per-group basis by setting the group 
attribute variable thread_arts to on/off in the file $home/ . t i n/attributes. 

If set on, show only new/unread articles; otherwise, show all articles. 

If set on, show a short descriptive text for each displayed newsgroup. The text used is taken from 

the $LIBDIR/newsgroups file. 

If set None, only the "Subject:" line will be displayed. If set Addr, "Subject:" line and the address 
part of the "From:” line are displayed. If set Name, "Subject:" line and the author's full name part of 
the "From:" line are displayed. If set Both, "Subject:" line and all of the "From:” line are displayed. 
This specifies the default type of post processing to perform on saved articles. The following types 
of processing are allowed: 

■ N one 

■ U npacking of multipart shell archives 

■ Unpacking of multipart uuencoded files 

■ Unpacking of multipart uuencoded files, which produce a *. zoo archive whose contents are 
listed 

■ Unpacking of multipart uuencoded files, which produce a *. zoo archive whose contents are 
extracted 

■ Unpacking of multipart uuencoded files, which produce a *. zip archive whose contents are 
listed 
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Sort articles by 


Save directory 
M ail directory 


Printer 


■ Unpacking of multipart uuencoded files, which produce a *. zip archive whose contents are 
extracted 

■ Unpacking of multipart uuencoded files, which produce an *.iha archive whose contents are 
listed (AmigaD OS version only) 

■ Unpacking of multipart uuencoded files, which produce an *.iha archive whose contents is 
extracted (AmigaDOS version only) 

This specifies how articles should be sorted. The following sort types are allowed: 

■ Don't sort articles (default). 

■ Sort articles by "Subject:" field (ascending and descending). 

■ Sort articles by "From:" field (ascending and descending). 

■ Sort articles by “D ate" field (ascending and descending). 

The directory where articles/threads are to be saved. Default is$HOME/News. 

T he di rectory where articles/threads are to be saved in mailbox format. Thisfeatureismainly for 
use with the eim mail program. It allows theuser to save articles, threads, or groups simply by 
giving = asthefilenameto save to. 

The printer program with options that is to be used to print articles. Default isipr for BSD 
machines and ip for SysV machines. 


tinrc CONFIGURABLE VARIABLES 


T he followi ng variables are user-configurable by editing $home/. tin/tin r-c directly. It is hoped to eventually provide a menu 
to allow the setting of the most common variables. 


batch_save 

beginner_level 

display_reading_prompt 

force_screen_redraw 

groupname_max_length 

default_sigfile 

editor_format 

hot_art_mark 

quote_chars 

reread_active_file_secs 

return_art_mark 

save_to_mmdf_mailbox 

show_last_line_prev_page 


If set on, articles/threads will be saved in batch mode when save -s or mail -m is specified on 
thecommand line. Default isoFF. 

If set on, a mini-menu of the most useful commands will be displayed at the bottom of the 
screen for each level. Default isoN. 

The prompt Reading. .. will be displayed when reading an article from an N NTP server to 
provide feedback to theuser. D efault is on. 

Specifies whether a screen redraw should always be done after certain external commands. 
Default isoFF. 

Maximum length of the names of newsgroups to be displayed so that more of the 
newsgroup description can bedisplayed. D efault is 132 . 

The path that specifies the signature file to use when posting, following up to, or replying to 
an article. If the path is a directory, then the signature will be randomly generated from files 
that are in the specified directory. Default is$HOME/.sig. 

The format string used to create the editor start command with parameters. D efault is %e 
+%N %F (for example /bin/vi +7 .article). 

The character used to show that an articl^thread is autoselected (hot). Default is*. 

The character used in quoting included text to article follow-ups and mail replies. The 1 
character represents a blank character and is replaced with 1 1 when read. Default is 1 : \ 
The news active file is reread at regular intervals to show if any new news has arrived. 
Default is 300 seconds. 

The character used to show that an article will return. Default is -. 

Allows articles to be saved to an mmdf-style mailbox instead of mbox format. D efault isoFF 
unless reading news on SCO U N IX, which uses mmdf by default. 

The last line of the previous page will bedisplayed as the first line of next page. D efault is 

OFF. 
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slow_speed_terminal 

tab_after_X_selection 

tab_goto_next_unread 

unread_art_mark 

use_builtin_inews 

use_keypad 


Strips the blanks from the end of each line, thereby speeding up the display when reading 
on a slow terminal or via modem. Default is off. 

If enabled, will automatically go to the first unread article after having selected all hot 
articles and threads with thex command at group index level. D efault is off. 

If enabled, pressing Tab at the article viewer level will go to the next unread article 
immediately instead of first paging through the current one Default is on. 

The character used to show that an article has not been read. Default is+. 

Allows the built-in N NTP inews to be enabled/disabled. Default is on (enabled). 

Allows the scroll keys on thekeypad to be enabled/disabled on supported terminals Default 

iSOFF. 


GROUP ATTRIBUTES 

tin allows certain attributes to beset on aper-group basis. These group attributes are read from thefile $home/.- tin/ 
attributes. A later version will provide a menu interface to set all the attributes. At present, you will have to edit thefile 
with your editor:-(. The following group attributes are available: 

newsgroup=alt.sources 

maildir=/usr/iain/Mail/sources 

savedir=/usr/iain/News/alt.sources 

sigfile=/usr/iain/.funny sig 

organization=Wacky Bits Inc. 

followup to=alt.sources.d 

printer=/usr/local/bin/a2ps -nn j /bin/lpr 

auto save=ON 

batch save=OFF 

delete tmp files=ON 

show only unread=OFF 

thread arts=ON 

show author=1 

sort art type=5 

post proc type=1 

N ote that the newsgroup=<groupname> line has to be specified before the attributes are specified for that group. 

All attributes are set to a reasonable default so you only have to specify the attribute that you want to change (for example, 

savedir). 

All toggle attributes are set by specifying on/off. 

T he show_author attribute is specified by a number from the following range: o=none i=username, 2=network address, 
3 =both. 

T he sort_art_type attribute is specified by a number from the following range 0=none, i=subject descending, 2=subject 
ascending, 3 =from descending, 4 =from ascending, 5 =date descending, 6 =date ascending. 

T he post_proc_type attribute is specified by a number from the following range: o=none i=unshar, 2 =uudecode, 
3=uudecode& list zoo archive, 4=uudecode& extract zoo archive, 5=uudecode& list zip archive, 6=uudecode & extract zip 
archive. (If running on AmigaDOS, the zoo options are replaced by their correspond! ngiha archiver options.) 

AUTOMATIC KILL AND SELECTION 

When there is a subject or an author that you are either very interested in, or find completely uninteresting, you can easily 
instruct tin to autoselect or autokill articles with specific subjects or from specific authors. These i nstructions are stored in a 
kill file. 

This menu is accessed by pressing "k at the group and page levels. It allows the user to kill or select an article that matches 
the current "Subject:" line, "From:” line or a string entered by the user. The user-entered string can be applied to the 
"Subject:” or "From:” lines of an article. The kin description can be limited to the current newsgroup or it can apply to all 
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newsgroups. Once entered, the user can abort the command and not save the km description, edit the km file or save the 
kill description. 

On starting tin, the user's kill file $HOME/.t in /kin is read and on entering a newsgroup any kin or select descriptions 
are applied. 

Articles that match a km description are marked killed and are not displayed. Articles that match an autoselect description 
are marked with an * when displayed. 

POSTING ARTICLES 

tm allows posting of articles, follow-up to already posted articles, and replying direct through mail to the author of an 
article. 

Use the w command to post an article to a newsgroup. After entering the post subject, the default editor (such asvi) or the 
editor specified by thesvisuAL environment variable will be started and the article can be entered. T o crosspost articles, 
simply add a comma and the name of thenewsgroup(s) to the end of the "N ewsgroups'' line at the beginning of the article. 
After saving and exiting the editor, you are asked if you wish to abort posting the article, edit the article again or post the 
article to the specified newsgroup(s). 

Use the w command to display a history of the articles you have posted. The date the article was posted, which newsgroups 
the article was posted to, and the article's subject line are displayed. 

Usethet/F command to post a follow-up article to an already posted article. The t command will copy the text of the 
original article into the editor. The editing procedure is the same as when posting an article with thew command. 

Usether/R command to reply direct through mail to the author of an already posted article. Ther command will copy the 
text of the ori gi nal article i nto the editor. T he editing procedure is the same as when posti ng an article with the w command. 
After saving and exiting the editor, you are asked if you wish to abort sending the article, edit the article again, or send the 
article to the author. 

CUSTOMIZING THE ARTICLE QUOTE STRING 

When posting a follow-up to an article or replying direct to the author of an article via e-mail, the text of the article can be 
quoted. The beginning of the quoted text can contain information about the quoted article (for example, theN ameand the 
M essagelD of the article). To allow for different situations, certain information from the article can be used in the quoted 
string. The following variables are expanded if found in thetinrc variables maii_quote_format= or news_quote_format=: 

%a Address (e-mail) 

%d D ate 

%f Full address (%n <%a)) 

%g Groupname 

%m M essage ID 

%n Name of user 

For example, 

nail_quote_format=On %D in %G you wrote: 
news_quote_format=In %M, %F wrote: 

would expand when used to: 

On 21 Jul 1992 09:45:51 -0400 in alt.sources you wrote: 

In <abcINN123@anl433.uucp>, Iain Lea (iain@erlm.siemens.de) wrote: 

MAILING, PIPING, PRINTING, REPOSTING, AND SAVING ARTICLES 

Thecommand interface to mail (m), pipe (|), print (o), crosspost(x) and save(s) articles isthe same for ease of use. 

The initial command will ask you to select which article thread, hot (autoselected) regex pattern, tagged articles you wish to 
mail, pipe, and so on. 
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T agged articles must have already been tagged with the t command. All tagged articles can be untagged by the u untag 
command. 

If regex pattern matching is selected, you are asked to enter a regular expression (for example, to match all article subject 
linescontaining net News, you must enter *net News*). Any articlesthat match theentered expression will be mailed, 
piped, and so on. 

T o save articles to a mailbox with the name of the current newsgroup (for example, Ait. sources) enter = or =<maiibox 
name> when asked for the save filename. 

T O Save articles in <newsgroup name>/<filename> format, enter +<filename>. 

When saving articles, you can specify whether the saved files should be post processed (such asunshar shell archive, 
uudecode multiple parts, and so on). A default process type can beset by the Process type in the m Options menu. 

AUTOMATIC MAILING AND SAVING NEW NEWS 

tm allows new/unread news articles to be mailed (-m opti on)/saved (-s option) in batch mode for later reading— useful 
when going on holiday and you don't want to return and find that expire has removed a whole load of unread articles. It's 
best to run from crontab every day while away, after which you will be mailed a report of which articles were mailed/saved 
from which newsgroups and the total number of articles mailed/saved. Articles are saved in a private news structure under 
your <savedir> directory (default is$HOME/News). 

Becareful of using this option if you read a lot of groups because you could overflow your filesystem. If you only want to 
save a few groups, it would be best to back up your full $HOME/.newsrc and create a new one that only contains the 
newsgroups you want to mail/save. Saved news can be read later by tin -r. 

tin -m iain -c -f newsrc.maii M ail any unread articles in newsgroups specified in file newsr-c. mail 

tin -s -c -f newsr-c. save Save any unread articles in newsgroups specified in file newsrc. save 

tin -r Read any articles saved by tin -s 

SIGNATURES 

tin will recognize a signature in either $home/ .signature or shome/. sig. If $home/. signature exists, then the signature 
will be pulled into the editor for mail commands. A signature in shome/. signature will not be pulled into the editor for 
posting commands because inews will append the signature itself. 

A signature in $HOME/.sig will be pulled into the editor for both posting and mailing commands. 

The following is an example of a$HOME/.sig file: 

NAMES Iain Lea iain.lea@erlm.siemens.de 

SNAIL Bruecken Strasse 12, 8500 Nuernberg 90, Germany 

PHONE +49-911-331963 (home) +49-911-3089-407 (work) 

tin also has the capability to generate random signatures on a per-newsgroup basis if so desired. The way to accomplish this 
is to specify the default signature or the group attri bute si gfi leas a directory. If, for example, the sigfile path is/usr/iain/ 
.sigs and .sigs is a di rectory, then tin will select a random signature from any file that is in the directory .sigs (note one 
signature per numbered file). A random signature can also consist of a fixed part signature that can contain your name, 
address, and so on, followed by the random sig. Thefixed part of the random sig is read from thefile shome/. sigtixed. 

ENVIRONMENT VARIABLES 

tinrc D efine this variable if you want to specify command-lineoptionsthat tin should be started with to 

save typing them each time it is started. The contents of the environment variable are added to the 
front of the command-line options before it is parsed, therefore allowing an option specified on the 
command line to override thesameoption specified in the environment. 
tin_homedir D efi ne this vari able if you do not want the .tin directory in shome/ .tin . For example, if you want 

all tin's private files in /tmp/ .tin, you would set tindir to /tmp. 
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TIN_INDEXDIR 

TIN_LIBDIR 

TIN_SPOOLDIR 

TIN_NOVROOTDIR 

TIN_ACTIVEFILE 

NNTPSERVER 

DISTRIBUTION 

ORGANIZATION 

REPLYTO 

ADDADDRESS 


BUG_ADDRESS 

MAILER 

VISUAL 

AUTOSUBSCRIBE 


Define thisvariableif you do notwantthe .index directory in $home/. tin/.index. For example 
if you want all tin's index files in /tmp/ .index, you would set tin__indexdir to /tmp. 

D efinethis variable if you want to override the libdir path that was compiled into the tin binary 
via the Makefile. 

Define this variable if you want to override the spooldir path that was compiled into the tin 
binary via the Makefile. 

Define this variable if you want to overridetheNovRooTDiR path that was compiled into the tin 
binary via the Makefile. 

Define this variable if you want to override the libdir/ active path that was compiled into the tin 
binary via the Makefile. 

T he default N NTP server to remotely read news from. This variable only needs to beset if the -r 
command-line option is specified and thefile /etc/nntpserver does not exist. 

Set the article header field "Distribution:" to the contents of the variable instead ofthesystem 
default. 

Set the article header field "Organization:” to the contents of the variable instead ofthesystem 
default. Thisvariable has precedence over thefile$HOME/. tin/organization that may also contain 
an organization string. If you are reading news on an Apollo DomainOS machine the environment 
variable newsorg has to be used instead of organization. 

Set the article header field "Reply-T o:" to the return address specified by the variable. This is useful 
if the machine is not registered in theUUCP mail maps or if you wish to receive replies at a 
different machine. Thisvariable has precedence over the file $home/ . tin /repiyto that may also 
contain a return address. 

This can contain an address to append to the return address when replying directly through mail to 
somebody whose mail address is not directly recognized by the local host. For example say the 
return address is user@bigvax, but bigvax is not recognized by your host, so therefore the mail 
will not reach user. But the host uttevax is known to recognize your host and bigvax, so if 
addaddress is set (for example, setenv add_address @nttevax for csh or 
set ADD_ADDRESS @littevax 

and export add address for sh), the address 

user@bigvax@littlevax will beusedand the mail will reach user^bigvax. 

This variable has precedence over the file 
$HOME/.tin/add_address 
that may also contain an address. 

If the b command bug report mail address is not correct, thisvariable should be set to the correct 
mail address. T his variable has precedence over thefile 

$HOME/.tin/bug_address 

that may also contain a mail address. 

This variable has precedence over the default mailer that is used in all mailing operations within 
tm (for example replying rR, and bug reports b). 

This variable has precedence over the default editor (for example, vi) that is used in all editing 
operations within tin (for example postingw, replying rR, foilow-upstF, and bug reportSB). 
tin interprets this vari able simi larly to rn. It contains a list of patterns, separated by commas and 
possibly prefixed with exclamation points A new group ischecked against the list of patterns; if it 
matches, tin subscribestheuserto the group without further query. An exclamation point negates 
the meaning of a match on this pattern and can be used to cancel certain matches. For example, 
setting AUTosuBscRiBE=comp. os. unix.*, talk.*, i talk. politics .* wi II automatically subscribe 
the user to all newsgroups in the comp. os. unix hierarchy, and all talk groups other than 
talk, politics groups (which will be queried for as usual). 
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autounsubscribe tin i interprets this variable simi larly to rn. It is handled like the autosubscribe variable, but 
groups matching the list are unsubscribed from without further query. For example setting 
AUTouNsuBscRiBE=ait.f lame. * , u*, !uk. * will automatically unsubscribe the user from all new 
ait. flame groups and all groups starting with u (university groups) other than uk groups (which 
will be queried for as usual). 


TIPS AND TRICKS 

tin can pretty much be navigated by using the four cursor keys. The left-arrow key goes up a level, the right-arrow key goes 
down a level, the up-arrow key goes up a line (or page, at article viewer level) and the down-arrow key goes down a line (or 
page, at article viewer level). 


The following newsgroups provide useful information concerning news software: 


--news.software.readers 
- - news.software.nntp 
--news.software.b 
--news.answers 


Information about news user agents tin, rn, nn, vn, and so on 
Information about NNTP 

Information about news transport agents Bnews, cnews, and inn) 
Frequently asked questions (FAQ s) about many different themes 


M any prompts (for example, Mark everything as read? (y/n) :) within tin offer a default choice that the cursor is 
positioned on. W hen you press <CR>, the default value istaken. 

M any prompts (for example, Post subject n>) within tin can beaborted by pressing <ESC>. 

When tin is run in an xterm window, it will resize itself each time the xterm is resized, 
tin will reread theactive file at set intervalsto show any newly arrived news. 


xterm BUTTONS 

If the environment variable term is set to xterm, then button pressing can be used to select groups and articles. 

In the Group Selection menu, if the mouse is pointing before the group's listing region, the previous page is selected (just 
like b). If the mouse is pointing after the group's listing region, the next page is selected (just like space). If the mouse is 
pointing at a group, then 

Left button M oves to the group pointed at 

Other buttons M oveto and select the group pointed at, just like <cr> 

In the Article menu, if the mouse is pointing before the article listing region, the previous page is selected (just like b). If the 
mouse is pointing after the article listing region, the next page is selected (just like space). If the mouse is pointing at an 
article then 

Left button M oves to the article pointed at 

Center button Reads next unread articlefrom that pointed at, just li ke <tab> 

Right button Reads article pointed at, just like <cr> 

In the Thread menu, if the mouse is pointing before the article listing region, the previous page is selected (just like b). If the 
mouse is pointing after the article listing region, the next page is selected (just like space). If the mouse is pointing at an 
article then 

Left button M oves to the article pointed at 

Center button Reads next unread articlefrom that pointed at, just like <TAB> 

Right button Reads article pointed at, just like <C R> 

In the Spool Selection menu, if the mouse is pointing before the spool listing region, the previous page is selected (just like 
b). If the mouse is pointing after the spool listing region, the next page is selected (just like space). If the mouse is pointing 
at a spool selection, then 
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Left button M oves to the spool pointed at 
Other buttons M oveto and select the spool pointed at, just like <cr> 

In other menus and areas, button pressing reverts back to usual cut and paste of xter-m, but after one click of any button. 

FILES 

$HOME/.newsrc 
$HOME/.newsauth 
$HOME/.tin/tinrc 
$HOME/.tin/attributes 
$HOME/.tin/.index 
$HOME/.tin/.mailidx 
$HOME/.tin/.saveidx 
$HOME/.tin/active.mail 
$HOME/.tin/active.save 
$HOME/.tin/add_address 
$HOME/.tin/bug address 
$HOME/.tin/kill 
$HOME/.tin/organization 
$HOME/.tin/posted 
$HOME/.tin/replyto 
$HOME/.signature 
$HOME/.Sig 
$HOME/.sigfixed 
/usr/lib/news/motd 
/usr/lib/news/newsgroups 
/usr/lib/news/subscriptions 

BUGS 

There are bugs somewhere among thecreepingfeaturism. Any bugs found should be reported by the b (bug report) 
command. 

Coredumps when setting certain toggle options from the Options menu at article viewer level. 

Coredumps when killing last article in a thread at article viewer level. 

HISTORY 

Based on the t ass newsreader that was developed by Rich Skrenta and posted to ait. sources in M arch 1991. tass was 
itself heavily influenced by notes, which was developed at the University of Illinois by Ray Essick and Rob Kolstad in 1982. 

vi .0 plo (full) was posted in eight parts to ait. sources on 23 Aug 1991. vi .0 pli (full) was posted in eight parts to 
ait. sources on 03 Sep 1991. vi .0 pl 2 (full) was posted in nine parts to ait. sources on 24 Sep 1991. vi .0 pl3 (patch) 
was posted in four parts to ait. sources on 30 Sep 1991. vi .0 pl4 (patch) was posted in two parts to ait. sources on 02 
Oct 1991. vi .0 PL5 (patch) was posted in four parts to ait. sources on 17 Oct 1991. vi .0 pl6 (patch) was posted in five 
parts to ait. sources on 27 N ov 1991. vi .0 pl7 (patch) was posted in two parts to ait. sources on 27 N ov 1991. vi .1 
plo (full) was posted in eleven parts to ait. sources on 13 Feb 1992. vi .1 pli (full) was posted in twelve parts to 
ait. sources on 24 M ar 1992. vi .1 pl 2 (patch) was posted in four parts to ait. sources on 30 M ar 1992. vi .1 pl3 (full) 
was posted in fifteen parts to ait. sources on 13 M ay 1992. vi .1 pl4 (full) was posted in fifteen parts to ait. sources on 
22 Jun 1992. vi .1 pls (patch) was posted in ss/en parts to ait. sources on 11 Aug 1992. vi .1 pl6 (full) was posted in 


Subscribed to newsgroups 

nntpserver password pairs for N NTP servers that require authorization 
Options 

Contains user-specified group attributes 

N ewsgroups index files directory 

M ailgroups index files directory 

Saved newsgroups index files directory 

Active file of users mai Igroups 

Active file of users saved newsgroups 

Address to add to when replying through mail 

Address to send bug reports to 

Article kill and autoselection file 

String to replace default organization 

H istory of articles posted by user 

H ost address to use in "Reply-T 0 :'' mail header 

Signature 

Signature 

Fixed part of a randomly generated signature 

N ews message-of-the-day file 

Short description of all newsgroups 

List of newsgroups to subscribe first-time user to 
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fifteen parts to ait.sources on 14 Sep 1992. vi .1 pl7 (patch) was posted in ten parts to ait.sources on 15 N ov 1992. 
vi .1 pls (patch) was posted in six parts to ait. sources on 06 Dec 1992. vi .1 pl9 (patch) was posted in three parts to 
ait.sources on 20 M ar 1993. vi .2 plo (full) was posted in fourteen parts to ait.sources on 25 M ay 1993. vi .2 pli 
(patch) was posted in eight parts to ait. sources on 14 J ul 1993. vi .2 pl 2 (patch) was posted in parts to ait. sources in 
September 1993. 
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tload 

tioad— Graphic representation of system load average 

SYNOPSIS 

tload [ - s scale] [-d delay] [tty] 

DESCRIPTION 

tioad prints a graph of the current system load average to thespecified tty (orthetty of the tioad process if none is 
specified). 

OPTIONS 

The -s scale option allows a vertical scale to be specified for the display (in characters between graph ticks); thus, a smaller 
value represents a larger scale, and vice versa. 

The -d delay setsthedelay between graph updates in seconds. 

FILES 

/proc/ioadavg Load average information 

SEE ALSO 

ps(l), top(l), uptime(l), w(l) 

BUGS 

The -d delay option sets the time argument for an aiarm(2); if -d 0 is specified, the alarm is set to 0 , which will never send 
the sigalrm and update the display. 

AUTHORS 

Branko Lankester, David Engel (david@ods.com), and M ichael K. Johnson (johnsonm@sunsite.unc.edu) 

Cohesive Systems 20 M arch 1993 


top 

top— D isplay top C PU processes 

SYNOPSIS 

top [ -][ddelay][q][S][s][i] 

DESCRIPTION 

top provides an ongoing look at processor activity in real time. It displays a listing of the most CPU-intensive tasks on the 
system, and can provide an interactive interface for manipulating processes. 
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COMMAND-LINE OPTIONS 

d Specifies the delay between screen updates. You can change this with thes interactive command. 

q This causes top to refresh without any delay. I f the caller has superuser privileges, top runs with the highest 

possible priority. 

s Specifies cumulative mode, where each process is listed with the CPU time that it as well as its dead children has 

spent. This is like the -s flag to ps(l). See the discussion of thes interactive command later in this manual page. 

s Tells top to run in secure mode. This disables the potentially dangers of the interactive commands. (See 

"Interactive Commands,'' later in this manual page.) A secure top isa nifty thing to leave running on a spare 
terminal. 

i Start top, ignoring any idleorzombieprocesses. (See the interactive command i.) 


FIELD DESCRIPTIONS 


top displays a variety of information about the processor state. The display is updated every five seconds by default, but you 
can change that with thed command-line option or thes interactive command. 


uptime 


processes 

CPU states 


Mem 


Swap 


PID 

USER 

PRI 

NI 

SIZE 

RSS 

SHRD 

ST 

TIME 


%CPU 

%MEM 

COMMAND 


This line displays the time the system has been up, and the three load averages for the system. The load 
averages are the average number of process ready to run during the last 1, 5, and 15 minutes. This line is 
just like the output of uptime(l). 

The total number of processes running at the time of the last update. This is also broken down into the 
number of tasks that are running, sleeping, stopped, or undead. 

Shows the percentage of CPU time in user mode, system mode; niced tasks, and idle. (N iced tasks are only 
those whose nice value is negative.) Time spent in niced tasks will also be counted in system and user 
time, so thetotal will be more than 100 percent. 

Stati sties on memory usage, including total availablememory, free memory, used memory, shared 
memory, and memory used for buffers. 

Statistics on swap space, including total swap space, available swap space, and used swap space. This and 
Mem are just like the output of f ree(l). 

The process ID of each task. 

The username of the task's owner. 

The priority of the task. 

T he nice value of the task. N egative nice values are lower priority. 

The size of the task's code plus data plus stack space, in kilobytes, isshown here. 

Thetotal amount of physical memoryused by the task, in kilobytes, isshown here. 

The amount of shared memoryused by th e task isshown in thiscolumn. 

The state of the task isshown here. The state is either s for sleeping, d for uninterruptible sleep, r for 
running, z for zombies, or t for stopped or traced. 

T otal CPU time the task has used since it started. If cumulative mode is on, this also includes the C PU 
time used by the process's children that have died. You can set cumulative mode with thes command-line 
option or toggle it with the interactive commands. 

Thetask's share of the CPU time since the last screen update, expressed as a percentage of total CPU time. 
The task's share of the physical memory. 

The task's command name, which will be truncated if it is too long to be displayed on one line. T asks in 
memory will have a full command line, but swapped-out tasks will only have the name of the program in 
parentheses, for example, (getty). 


INTERACTIVE COMMANDS 

Several single-key commands are recognized while top is running. Some are disabled if thes option has been given on the 
command line 
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■ l E rases an d red raws th e screen. 

h or ? D isplaysa help screen giving a brief summary of commands, and the status of secure and cumulative modes, 
k Kill a process. You will be prompted forthepiD of the task, and the signal to send to it. For a normal kill, send 

signal 15 . Forasure, but rather abrupt, kill, send signal 9 . The default signal, as with kiii(l), is 15 , sigterm. 
This command is not available in secure mode, 
i Ignoreidleand zombie processes. This is a toggle switch. 

n or# Change the number of processes to show. You will be prompted to enter the number. This overrides automatic 

determination of the number of processes to show, which is based on window size measurement. If 0 is specified, 
then top will show as many processes as will fit on the screen; this is the default, 
q Quit. 

r Renice a process. You will be prompted for the pid of the task, and the value to nice it to. Entering a positive 

value will cause a process to beniced to negative values, and lose priority. If root is running top, a negative value 
can be entered, causi ng a process to get a higher than normal priority. The default renice value is 10 . This 
command is not available in secure mode. 

s T his toggles cumulative mode, the equivalent of ps -s, in other words, that CPU timeswill include a process's 

defunct children. For some programs, such as compilers, which work by forking into many separate tasks, normal 
mode will make them appear less demanding than they actually are. For others, however, such as shells and imt, 
this behavior is correct. In any case try cumulative mode for an alternative view of CPU use. 
s Change the delay between updates. You will be prompted to enter the delay time in seconds, between updates. 

Fractional values are recognized down to microseconds. Entering© causes continuous updates. The default value 
is 5 seconds. N otethat low values cause nearly unreadably fast displays, and greatly raise the load. Thiscommand 
is not available in secure mode. 

NOTES 

T his proc- based top works by reading the files in the proc filesystem, mounted on /proc. If / proc is not mounted, top will 
not work. 

%cpu shows the cputim^realti me percentage in the period of time between updates. For the first update, a short delay is 
used, and top itself dominates the CPU usage. After that, top will drop back, and a more reliable estimate of CPU usage is 
available. 

The size and rss fields don't count the page tables and the task struct of a process; this is at least 12K of memory that is 
always resident, size isthevirtual sizeof the process (code+data+stack). 

Keep in mind that a process must die for its time to be recorded on its parent by cumulative mode. Perhaps more useful 
behavior would be to follow each process upwards, adding time but that would be more expensive, possibly prohibitively so. 
In any case, that would make top's behavior incompatible with ps. 

SEE ALSO 

ps( 1), free(l), uptime(l), kill(l), renice(l). 

BUGS 

If thewindow islessthan about 70x7, top will not format information correctly. 

AUTHOR 

top was originally written by Roger Binns, based on Branko Lankester's(iankeste@fwi.uva.ni) ps program. Robert N ation 
(nation@rocket.sander-s.iockheed.com) rewrote it significantly to use the proc filesystem, based on M ichael K. Johnson's 
(johnsonm@sunsite.unc.edu) proc-based ps program. M any changes were made, including secure and cumulative modes 
and a general cleanup, by M ichael Shields (mjshieid@nyx.cs.du.edu). 


Linux, 1 Februaryl993 
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touch 

touch— Change filetimestamps 

SYNOPSIS 

touch [-acfn] [-r reference-file] [-t MMDDhhmm[ [CC]YY] [.ss]] [-d t i me] 

[ --time={at i me, access, use, mt i me, modify}] [ --date=t i me ] [ - - f ile=r eference-fi I e ] 

[•-no-create] [--help] [--version] file... 

DESCRIPTION 

This manual page documents the GN U version of touch, touch changes the access and modification times of each given file 
to the current time. Files that do not exist are created empty. If the first filename given would be a valid argument to the-t 
option and no timestamp is given with any of the -d, -r, or -t options and the - - argument is not given, that argument is 
interpreted as the time for the other files instead of as a filename. 

If changing both the access and modification times to the current time touch can change the timestamps for files that the 
user running it does notown but has write permission for. Otherwise, the user must own the files. 

OPTIONS 

-a, - -time=at i me, 

--time=access, 

- -time=u s e 
-c, --no-create 
-d, - -date t i me 

-f 

-m, - -time=mt i me, 

--time=modi f y 

- r, - -file reference-fi I e 
-t MMDDhhmm[ [ CC] YY] [ .ss ] 

- -help 

- -version 

GNU File Utilities 


Changetheaccesstimeonly. 

Do not create files that do not exist. 

Uset i me (which can bein various common formats) instead of the current time. Itcan 
contain month names, time zones, am and pm, and so on. 

Ignored; for compatibility with BSD versions of touch. 

Change the modification timeonly. 

U sethetimesof r ef er ence - f i i e instead of the current time. 

Use the argument (months days, hours minutes, optional century and years, optional 
seconds) instead of the current time. 

Print a usage message on standard output and exit successfully. 

Print version information on standard output, then exit successfully. 


tr 

tr— Translate or delete characters 

SYNOPSIS 

tr [-cst] [--complement] [--squeeze-repeats] [--truncate-setl] stringl s t rin g 2 
tr f-s,--squeeze-repeatsg [-c] [--complement] stringl 
tr f-d,--deleteg [-c] stringl 


tr f-d,--deleteg f-s,--squeeze-repeatsg [-c] [--complement] stringl s t rin g 2 

GNU tr also acceptsthe --help and --version options. 
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DESCRIPTION 

This manual page documents the GN U version of tr. tr copies the standard input to the standard output, performing one 
of the following operations: 

■ Translate and optionally squeeze repeated characters in the result 

■ Squeeze repeated characters 

■ Delete characters 

■ D elete characters, then squeeze repeated characters from the result. 

Thest r i ngi and (if given) s t r i ng2 arguments define ordered sets of characters, referred to below asset 1 and set 2. These 
sets are the characters of the input that tr operates on. The - - complement (-c) option replaces s e 11 with its complement (all 
of th e characters that are not in s e 11). 


SPECIFYING SETSOFCHARACTERS 

The format of the s t r i n g 1 and st r i n g 2 arguments resembles the format of regular expressions; however, they are not regular 
expressions only lists of characters. M ost characters simply represent themselves in these strings, but the strings can contain 
the shorthands in the following list, for convenience. Some of them can be used only in st r i ngi or st r i n g 2 , as noted. 

Backslash escapes. A backslash followed by a character not listed causes an error message. 

\a Control-G 

\b Control-H 

\f Control-L 

\n Control-J 

\r Control-M 

\t Control-I 

\v Control-K 

\ 000 The character with thevalue given by 000, which isl to 3 octal digits 

\n A backslash 

Ranges The notation m-n expands to all of the characters from m through n, in ascending order, m should collate before n; if 
it doesn't, an error results. As an example, 0-9 isthe same as 0123456789. Although GN U tr does not support the System 
V syntax that uses square brackets to enclose ranges, translations specified in that format will still work as long as the brackets 
in st r i ngi correspond to identical brackets in st ri ng 2 . 

Repeated characters. The notation [c*n] i n s t r i n g 2 expands ton copies of character c. Thus, [y*6] isthe same as yyyyyy. 
The notation [ c*] in s t r i n g 2 expands to as many copies of c as are needed to make set 2 as long as set 1 . If n begins with a 
0 , it is interpreted in octal, otherwise in decimal. 

Character classes. The notation [: class -name: ] expands to all of the characters in the (predefined) class named class- 
name. The characters expand in no particular order, except for the upper and lower classes, which expand in ascending 
order. When the - - delete (-d) and - - squeeze -repeats (-s) options are both given, any character class can be used in 
st ri ng 2 . Otherwise, only the character classes lower and upper are accepted in st ri n g 2 , and then only if the corresponding 
character class (upper and lower, respectively) is specified in the same relative position in s t ri ngi . Doing this specifies case 
conversion. The class names are given in the following list; an error results when an invalid class name is given. 

ainum Letters and digits 

alpha Letters 

blank H orizontal whitespace 
cntri Control characters 

digit Digits 

graph Printablecharacters, not including space 

lower Lowercase letters 
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print 

Printablecharacters, including space 

punct 

Punctuation characters 

space 

H orizontal or vertical whitespace 

upper 

Uppercase letters 

xdigit 

H exadecimal digits 


Equivalence classes. Thesyntax [=c = ] expands to all of the characters that are equivalent to c, in no particular order. 
Equivalence classes are a recent invention intended to support non-English alphabets. But there seems to beno standard way 
to define them or determine their contents. Therefore they are not fully implemented in GN U tr; each character's 
equivalence class consists only of that character, which makes this a useless construction currently. 

TRANSLATING 

tr performs translation when st r f ngi and st ri n g 2 are both given and the - -delete(-d) option is not given, tr translates 
each character of its input that is in set 1 to the corresponding character in set 2. Characters not in set 1 are passed through 
unchanged. When a character appears more than once in set 1 and the corresponding characters in set 2 are not all the same, 
onlythefinal oneisused. For example, these two commands are equivalent: 
tr aaa xyz 

tr a z 

A common use of tr is to convert lower case characters to uppercase. This can be done in many ways. H ere are three of them: 

tr abcdefghij klmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ 
tr a-z A-Z 

tr 1 [:lower:] 1 1 [ :upper:] 1 

When tr is performing translation, set 1 and set 2 should normally have the same length. If set 1 is shorter than set 2, the 
extra characters at the end of s et 2 are ignored. 

On the other hand, making s et 1 longer than set 2 is not portable; POSIX.2 says that the result is undefined. In this 
situation, the BSD tr pads set 2 to the length of set 1 by repeating the last character of set 2 as many times as necessary. The 
System V tr truncates set 1 to the length of set 2 . 

By default, GN U tr handles this case like the BSD tr does. W hen the - - truncate-set 1 (-t) option is given, GN U tr 
handles this case like the System V tr instead. This option is ignored for operations other than translation. 

Acting like the System V tr in this case breaks the relatively common BSD idiom: 

tr -cs A-Za-z0-9 1 n012 1 

because it converts only zero bytes (the first element in thecomplementofseti), rather than all nonalphanumerics, to 
newlines. 

SQUEEZING REPEATS AND DELETING 

When given just the - - delete (-d) option, tr removes any input characters that are in set 1 . 

When given just the - - squeeze- repeats (-s) option, tr replaces each input sequence of a repeated character that is in set 1 
with a si ngle occurrence of that character. 

When given both the - - delete and the - - squeeze-repeats options, tr first performs any deletions using set i, then 
squeezes repeats from any remaining characters using s et 2. 

The - - squeeze-repeats option may also be used when translating, in which casetr first performs translation, then squeezes 
repeats from any remaining characters using s et 2. 

H ere are some examples to illustrate various combinations of options. 
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Remove all zero bytes: 
tr -d 1 n000 1 

Put all words on lines by themselves. This converts all nonalphanumeric characters to newlines, then squeezes each string of 
repeated newlines into a single newline: 

tr -cs '[a-zA-Z0-9] 1 ' [nn*]' 

Convert each sequence of repeated newlines to a single newline 
tr -s 'nn' 

GNU tr also accepts the following options in any combination with the others. 

- - help Print a usage message and exit with a non-zero status. 

--version Print version information on standard output, then exit. 

WARNING MESSAGES 

Setting the environment variable posixly_correct turns off several warning and error messages, for strict compliance with 
PO SIX.2. The messages normally occur in the following circumstances: 

1. When the - - delete option is given but - - squeeze -repeats is not, and st r i ng 2 is given, GN U tr by default prints a 
usage message and exits, because st r i n g 2 would not be used. The posix specification says that s t r i n g 2 must be ignored 
in this case. Silently ignoring arguments is a bad idea. 

2. When an ambiguous octal escape is given. For example, n400 is actually n40 followed by the digit 0 , because the value 
400 octal does not fit into a si ngle byte. 

N otethat GN U tr does not provide complete BSD or System V compatibility. For example there is no option to disable 
interpretation of the POSIX constructs [: alpha: ], [ =c= ] , and [ c*i 0 ]. Also, GNU tr does not delete zero bytes automati¬ 
cally, unlike traditional U N IX versions, which provide no way to preserve zero bytes. 

GNU Text Utilities 


tset,reset 

tset, reset— Terminal initialization 

SYNOPSIS 

tset [-IQrs] [-t] [-e ch] [-i ch] [-k ch] [-m mapping] [terminal] 
tset -h 
tset -V 

reset [-IQrs] [-t] [-e ch] [-i ch] [-k ch] [-m mapping] [terminal] 
reset -h 
reset -V 

DESCRIPTION 

tset initializes terminals, tset first determines the type of terminal that you are using. This determination is done as 
follows, using thefirst terminal typefound: 

■ Theterminal argument specified on thecommand line 

■ Thevalueof theTERM environmental variable 

■ Theterminal type associated with the standard error output device in the /etc/ttytype file 

■ The default terminal type, unknown 
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If the terminal type was not specified on thecommand line, the -m option mappings are then applied (seethefollowing 
section, "Options," for more information). Then, if theterminal type beginswith a question mark (?), theuser isprompted 
for confirmation of theterminal type. An empty response confirms thetype or, another type can be entered to specify a new 
type. After theterminal type has been determined, thetermcap entry for theterminal is retrieved. If no termcap entry is 
found for the type theuser isprompted for another terminal type. 

After thetermcap entry is retrieved, the window size, backspace interrupt, and linekill characters (among many other 
things) are set and theterminal and tab initialization strings are sent to the standard error output. Finally, if the erase, 
interrupt, and linekill characters have changed, or are not set to their default values, their values are displayed to the standard 
error output. 

When invoked as reset, tset sets cooked and echo modes, turns off cbreak and raw modes, turns on newline translation and 
resets any unset special characters to their default values before doing the terminal initialization described above. This is 
useful after a program dies leaving a terminal in an abnormal state. N ote, you may have to type<LF>r-eset<LF> (the line-feed 
character is normally control -j) to get theterminal to work, as carriage-return may no longer work in the abnormal state. 
Also, theterminal will often not echo the command. 

OPTIONS 

T h e opti o ns are as f o 11 ows: 

-t Theterminal type is displayed to the standard output, and theterminal is not initialized in anyway. 

-e Set the erase character to ch. 

-i Do not send theterminal or tab initialization strings to theterminal. 

-i Set the interrupt character to ch. 

-k Set the line kill character to ch. 

-m Specify a mapping from a port type to a terminal. See the following section, "Setting the Environment,” for more 
information. 

-r Print theterminal type to the standard error output. 

-s Print the sequence of shell commands to initialize the environment variables columns, lines, term, and termcap 
to the standard output. 

q Don't display any values for the erase, interrupt, and linekill characters. 

-w Force setting of display size as defined in /etc/termcap file, 

-h Print short usage message. 

-v Print version number. 

The arguments for the -e, -i, and -k options may either be entered as actual characters or by using the hat notation, for 
example, contr-oi-h may be specified as • h or' h. 

SETTING THE ENVIRONMENT 

It is often desirable to set theterminal type and information about the terminal's capabilities and display size in the shell's 
environment. This is done with the -s option; when this opti on is specified, the commands to enter the information into the 
shell's environment are output to the standard output. If the shell environmental variable ends in csh, the output 
commands are for the csh(l); otherwise, they are for sh(l). N ote, the output commands for the csh set and unset the shell 
variable nogiob. The foil owing line in the .login or .profile files will initialize the environment correctly: 
eval 'tset -s options ... 1 

TERMINAL TYPE MAPPING 

When theterminal is not hardwired into the system (or the current system information is incorrect), theterminal type 
derived from the / etc /ttytype file or the term environmental variable is often something generic like network, dialup, or 
unknown. When tset is used in a startup script .profile for sh(l) users or .login for csh(l) users), it is often desirable to 
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provide information about the type of terminal used on such ports. The purpose of the -m option is to map from some set of 
conditions to a terminal type; that is, to tell tset, "If I'm on this port at a particular speed, guess that I'm on that kind of 
terminal.’' 

Theargumentto the -moption consistsofan optional port type, an optional operator, an optional baud rate specification, an 
optional colon (:) character, and a terminal type. The port type is a string (delimited by either the operator or the colon 
character). The operator may beany combination of: &>, &<, &@, and &> means greater than, &< means less than, 
means equal to, and &i inverts the sense of the test. The baud rate is specified as a number and is compared with the speed of 
the standard error output (which should be the control terminal). The terminal type is a string. 

If the terminal type is not specified on the command line, the -m mappings are applied to the terminal type. If the port type 
and baud rate match the mapping, the terminal type specified in the mapping replaces the current type If more than one 
mapping is specified, the first applicable mapping is used. 

For example, consider the following: 

dialup> 9600 :vt 100 

The port type is dialup, the operator is >, the baud rate specification is 9600, and the terminal type is vt 100 . The result of 
this mapping is to specify that if the terminal typeisdiaiup, and the baud rate is greater than 9600 baud, a terminal type of 
vti 00 will beused. 

If no port type is specified, the terminal type will match any port type; for example, 

-m dialup:vt 100 -m :?xterm 

will cause any dialup port, regardless of baud rate, to match theterminal type: 

vt 100 , 

and any nondialup port type to match theterminal type: 

?xterm. 

N ote, because of the leading question mark, the user will be queried on a default port as to whether they are actually using an 
xter-m terminal. 

N 0 whitespace characters are permitted in the -m option argument. Also, to avoid problems with metacharacters, it is 
suggested that the entire -m option argument be placed within single quote characters, and that csh users insert a backslash 
character (\) before any exclamation marks(i). 

ENVIRONMENT 

The tset command utilizes the shell and term environment variables, 
tset can set columns, lines, term, and termcap environmental variables. 

FILES 

/etc/ttytype system Port nameto terminal type mapping database 
/etc/termcap Terminal capability database 

SEE ALSO 

csh(l), tcsh(l), sh(l),bash(l),stty(l), tty(4), termcap(5), ttytype(5), environ(7) 

HISTORY 

The tset command appeared in BSD 3.0. 
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COMPATIBILITY 

The-A, -e, -h, -s, -u, and -v options have been deleted fromthetset utility. N oneof them were documented in 4.3BSD 
and all are of limited utility at best. The -a, -d, and -p options are similarly not documented or useful, but were retai ned as 
they appear to be in widespread use. It is strongly recommended that any usage of these three options be changed to use the 
-m option instead. The -n option remains, but has no effect. It isstill permissibleto specify the -e, -i, and -k options 
without arguments, although it is strongly recommended that such usage be fixed to explicitly specify the character. 

Executing tset as reset no longer implies the -q option. Also, the interaction between the - option and the terminal 
argument in some historic implementations of tset has been removed and has been replaced with -t option. 

Finally, the tset implementation has been completely redone as part of the addition to thesystem of alEEE Stdl003.1- 
1988 (POSIX)-compliant terminal interface and will no longer compile on systemswith older terminal interfaces. 

Linux, 12 January 1995 
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tsort— Topological sort of a directed graph 

SYNOPSIS 

tsort [file] 

DESCRIPTION 

tsort takes a list of pairs of node names representing directed arcs in a graph and prints the nodes in topological order on 
standard output. Input is taken from the named file, or from standard input if no file is given. 

N ode names in the input are separated by whitespace, and there must bean a/en number of nodes. 

Presence of a node in a graph can be represented by an arc from the node to itself. This is useful when a node is not 
connected to any other nodes. 

If the graph contains a cycle (and thereto re can not be properly sorted), oneof the arcs in the cycle is ignored and the sort 
continues. Cycles are reported on standard error. 

SEE ALSO 

ar(l) 

HISTORY 

A tsort command appeared in AT&T v7. This tsort command and manual page are derived from sources contributed to 
Berkeley by M ichael Rendell of M emorial University of N ewfoundland. 

23 April 1991 
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twm— T ab W i ndow M anager for the X W i ndow System 

SYNTAX 

twm [ -display dpy ][-s ][-f initfile ][-v ] 

DESCRIPTION 

twm isawindow manager for the X Window System. It provides titlebars, shaped windows, several forms of icon manage¬ 
ment, user-defined macro functions, click-to-type and pointer-driven keyboard focus, and user-specified key and pointer 
button bindings. 
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This program is usually started by the user's session manager or startup script. When used from xdm(l) or xinit(l) without a 
session manager, twm is frequently executed in the foreground as the last client. When run this way, exiting twm causes the 
session to determinated (logged out). 

By default, application windows are surrounded by a "frame" with a titlebar at the top and a special border around the 
window. The titlebar contains the window's name, a rectangle that is lit when the window is receiving keyboard input, and 
function boxes known as t/t/ebuttonsat the left and right edges of the titlebar. 

Pressing pointer Buttonl (usually the leftmost button unless it has been changed with xmodmap) on atitlebutton will invoke 
the function associated with the button. In the default interface, windows are iconified by clicking (pressing and then 
immediately releasing) the left titlebutton (which looks like a dot). Conversely, windows are deiconified by clicking in the 
associated icon or entry in the icon manager. (See description of the variable show- iconManager and of the function 

f. showiconmgr.) 

Windows are resized by pressing the right titlebutton (which resembles a group of nested squares), dragging the pointer over 
the edge that is to be moved, and releasing the pointer when the outline of the window is the desired size. Similarly, windows 
are moved by pressing in the title or highlight region, dragging a window outline to the new location, and then releasing 
when the outline is in the desired position. Just clicking in the title or highlight region raises the window without moving it. 

When new windows are created, twm will honor any size and location information requested by the user (usually through - 
geometry command-line argument or resources for the individual applications). Otherwise, an outlineof thewindow's 
default size, its titlebar, and lines dividing the window into a 3x3 grid that track the pointer are displayed. Clicking pointer 
Buttonl will position thewindow atthecurrent position and give it the default size. Pressing pointer Button2 (usually the 
middle pointer button) and dragging the outline will give the window its current position but allow the sides to be resized as 
described above. Clicking pointer Button3 (usually the right pointer button) will give the window its current position but 
attempt to make it long enough to touch the bottom of the screen. 

OPTIONS 

twm accepts the following command-line options 
-display dpy This option specifies thex server to use. 

-s Thisoption indicates that only the default screen (as specified by -display or by the display environ- 

mentvariable) should be managed. By default, twm will attempt to manage all screenson thedisplay. 

-t f i i ename This option specifies the name of the startup file to use. By default, twm will look in the user's home 
directory for files named .twmrc.num (where num is a screen number) or .twmrc. 

-v Thisoption indicates that twm should print error messages whenever an unexpected X Error event is 

received. This can be useful when debugging applications but can be distracting in regular use. 

CUSTOMIZATION 

M uch of twm's appearance and behavior can be controlled by providing a startup file in one of the following locations 
(searched in order for each screen being managed when twm begins): 

$home/. twmrc.scr eenn umber T he s c r ee nn u mbe r is a small positive number (for example, 0 , i, and so on) 

representing the screen number (for example, the last number in the display 
environrnentvariablehost:dispiaynum.screennum) thatwould beused to contact 
that screen of thedisplay. This is intended for displays with multiple screens of 
differing visual types. 

$home/. twmrc T his is the usual nameforan individual user's startup file. 

<xRoot>/nb/xii /twm/system, twmrc If neither of the preceding fi les are found, twm will look in this file for a default 

configuration. This is often tailored by the site administrator to provide convenient 
menus or familiar bindings for novice users. <xRoot> refers to the root of theX11 
install tree. 
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If no startup files are found, twm will use the built-in defaults described. The only resource used by twm isbitmapFiiePath 
for a colon-separated list of directories to search when looking for bitmap files. For more information, seetheAthena 
W idgets manual and xrdb(l). 

twm startup files are logically broken up into three types of specifications: variables, Bindings, and Menus. The variables 
section must come first and is used to describe the fonts, colors, cursors, border widths, icon and window placement, 
highlighting, autoraising, layout of titles, warping, and use of the icon manager. The Bindings section usually comes second 
and isused to specify the functions that should beinvoked when keyboard and pointer buttons are pressed in windows, 
icons, titles, and frames. The Menus section gives any user-defined menus (containing functions to beinvoked or commands 
to be executed). 

V ariable names and keywords are case-in sensitive. Strings must be surrounded by double quote characters (for example, 
"blue") and are case-sensitive. A pound sign (#) outside of a string causes the remainder of the line in which the character 
appears to be treated as a comment. 

VARIABLES 

M any of the aspects of twm's user interface are control led by variables that may beset in the user's startup file. Some of the 
options are enabled or disabled simply by the presence of a particular keyword. Other options require keywords, numbers, 
strings, or listsof all of these. 

Lists are surrounded by braces and are usually separated by whitespaceor a newline. For example, 

AutoRaise { "emacs" "XTerm" "Xmh" } 
or 

AutoRaise 

{ 

"emacs" 

"XTerm" 

"Xmh" 

} 

W hen a variable containing a list of strings representing windows is searched (for example, to determine whether or not to 
enable auto raise, as shown in the preceding example), a string must bean exact, case-sensitive match to the window's name 
(given bythe wm_name window property), resource name, or class name (both given by thewM_cLAss window property). The 
preceding example would enable auto raise on windows named emacs as well as any xterm (because they are of class xTerm) or 
xmh windows (which are of class xmh). 

String arguments that are interpreted as filenames (seepixmaps, cursors, and iconDirectory in the following list of 
variables) will prepend the user's directory (specified by the home environment variable) if the first character is a tilde (-). If, 
instead, the first character is a colon (:), the name is assumed to refer to one of the internal bitmaps that are used to create 
the default titlebars symbols:: xiogo or delete (both refer to thex logo),: dot or: iconity (both refer to the dot),: resize 
(the nested squares used by the resize button),: menu (a page with lines), and : question (the question mark used for 
nonexistent bitmap files). 

T he foil owing variables may be specified at the top of a twm startup fi le. Lists of W i ndow name prefix strings are indicated by 
wi n- 1 1st. Optional arguments are shown in square brackets: 

AutoRaise { win-list ] T his variable specifies a list of windows that should automatically be raised whenever the 

pointer entersthewindow. Thisaction can be interactively enabled or disabled on 
individual windows using the function f .autoraise. 

AutoReiativeResize T his variable indicates that dragging out a window size (either when initially sizing the 

window with pointer Button2 or when resizing it) should not wait until the pointer has 
crossed thewindow edges. Instead, moving the pointer automatically causes the nearest edge 
or edges to move by the same amount. T his allows the resizing of windows that extend off 
the edge of the screen. If the pointer is in thecenter of thewindow, or if the resize is begun 



BorderColor s t ri n g 
windows, [{ wi ncol orl i st 


BorderTileBackground 
wi ncol orl i st }] 


BorderTileForeground 
string [{wincolorlist 


BorderWidth pi xel s 

Buttonlndent pixels 

ClientBorderWidth 
Color {colors-list } 
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by pressing a titlebutton, twm will still wait for the pointer to cross a window edge (to 
prevent accidents). This option is particularly useful for peoplewho I ike the press- 
drag-release method of sweeping out window sizes. 

This variable specifies the default color of the border to be placed around all noniconified 
}] and may only be given within a Color, Grayscale, or Monochrome list. The optional 
wincolorlist specifies a list of window and color name pairs for specifying particular 
border colors for different types of windows. For example: 

BorderColor 
"gray50" 

{ 

"XTerm" "red" 

"xmh" "green" 

} 

The default is black. 

This variable specifies the default background color in the gray pattern used in st r i ng [{ 
unhighlighted borders (only if NoHighiight hasn't been set), and may only be given within 
a Color, Grayscale, Or Monochrome list. T he Optional wincolorlist allows per-window 
colors to be specified. The default iswhite. 

This variable specifies the default foreground color in the gray pattern used in unhighlighted 
1 borders(only if NoHighiight hasn't been set), and may only be given within acoior, 
Grayscale, Or Monochrome list. T he optional wincolorlist allows per-window COlorstO be 
specified. The default is black. 

This variable specifies the width in pixels of the border surrounding all client window 
frames if ClientBorderWidth has not been specified. This value is also used to set the 
border size of windows created by twm (such astheicon manager). T he default is 2. 

This variable specifies the amount by which titlebuttonsshould be indented on all sides. 
Positive values cause the buttonsto be smaller than thewindow text and highlight area so 
that they stand out. Setting this and theiitieButtonBorderwidth variables to 0 makes 
ti tl ebutto n s as tal I and wide as possible. The default is 1 . 

This variable indicates that border width of a window's frame should beset to the initial 
border width of thewindow, rather than to the value of BorderWidth. 

This variable specifies a list of color assignments to be made if the default display is capable 
of displaying more than simple black and white Thecoi ors -1 i st is made up of the 
following color variables and their values: 

DefaultBackground 
DefaultForeground 
MenuBackground 
MenuForeground 
MenuTitleBackground 
MenuTitleForeground 
MenuShadowColor 
PointerForeground 
PointerBackground 

The following color variables may also be given a list of window and color name pairs to 
allow per-window colors to be specified (see BorderColor for details): 

BorderColor 
IconManagerHighlight 
BorderTitleBackground 
BorderTitleForeground 
TitleBackground 
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ConstrainedMoveTime 
mi I I i seconds 

Cursors {cursor-list } 


DecorateTransients 
DefaultBackground strin 


TitleForeground 
IconBackground 
IconForeground 
IconBorderColor 
IconManagerBackg round 
IconManagerForeground 
For example: 

Color 

{ 

MenuBackground "gray50" 

MenuForeground "blue" 

BorderColor "red" { "XTerm" "yellow" } 

TitleForeground "yellow" 

TitleBackground "blue" 

} 

All of these color variables may also be specified for the Monochrome variable, allowing the 
same initialization fileto beused on both color and monochrome displays. 

This variable specifies the length of time between button clicks needed to begin a 
constrained moveperation. Double-clicking within thisamount of time when invoking 
t .move will cause the window to be moved only in a horizontal or vertical direction. Setting 
this value to 0 will disable constrained moves. The default is 400 milliseconds. 

T his variable specifies the glyphs that twm should use for various pointer cursors. Each 
cursor may be defined either from the cursor font or from two bitmap files. Shapes from 
the cursor font may be specified directly as 
0 cursorname "string" 

wherecursorname is one of the cursor names listed below, andstri ng isthenameof a 
glyph as found in thefile: 

<XRoot>/include/XI1/cursorfont.h 

(without thexc prefix). If thecursor isto be defined from bitmap files, the following syntax 
is used instead: 

0 cursorname "image" "mask" 

T he i mage and mask strings specify the names of files containing the glyph image and mask 
in bitmap(l) form. T he bitmap files are located in the same manner as icon bitmap files. 
The following example shows the default cursor definitions: 


Cursors 

{ 

Frame 

"top_left_arrow 

Title 

"top_left_arrow 

Icon 

"top_left_arrow 

IconMgr 

"top_left_arrow 

Move 

"fleur" 

Resize 

"fleur" 

Menu 

"sb_left_arrow" 

Button 

"hand2" 

Wait 

"watch" 

Select 

"dot" 

Destroy 

"pirate" 

} 



This variable indicates that transient windows (those containing a wm_transient_for 
property) should have titlebars. By default, transients are not reparented. 

This variable specifies the background color to beused for sizing and information windows. 
The default iswhite. 




DefaultForeground string 

DontlconifyByUnmapping 
{ wi n - I i s t } 

DontMoveOff 

DontSqueezeTitle 
[{ wi n- I i s t }] 

Forcelcons 

FramePadding pixels 

Grayscale {colors } 

IconBackground string 
[{ wi n - I i s t }] 

IconBorderColor stri ng 
[ { wi n- I i s t } ] 

IconBorderWidth pi xel s 

IconDirectory stri ng 

IconFont stri ng 

IconForeground string 
[{ wi n- I i s t }] 

IconifyByUnmapping 
[{ wi n- I i s t }] 


IconManagerBackground 
string [{ wi n- I i st }] 


IconManagerDontShow 
[{ wi n- I i s t }] 
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This variable specifies the foreground colorto be used for sizing and information windows. 
The default is black. 

This variable specifies a list of windows that should not be iconified window (as would be 
the case if iconityByunmapping had been set). This is frequently used to force some 
windows to be treated as icons while other windows are handled by theicon manager. 
Thisvariableindicates that windows should not be allowed to be moved off thescreen. It 
can be overridden by the f.torcemove function. 

This variable indicates that titlebars should not be squeezed to their minimum size as 
described under squeezeTitie below. If the optional window list is supplied, only those 
windows will be prevented from being squeezed. 

This variable indicates that icon pi xmaps specified in the icons variable should override any 
client-supplied pixmaps. 

T his variablespecifiesthe distance between thetitlebar decorations (the button and text) 
and thewindow frame. The default is 2 pixels. 

T his variable specifies a list of color assignments that should be made if the screen has a 
Grayscale default visual. See the description of colors. 

This variable specifies the background color of icons and may only be specified inside of a 
color, Grayscale, or Monochrome list. T he optional win-iist isalistof window names and 
colors so that per-window colors may be specified. See the Border-color variable for a 
completedescription ofthewi n-1 i st .Thedefault iswhite. 

This variable specifies the color of the border used for icon windows, and may only be 
Specified inside Of a Color, Grayscale, Or Monochrome list. T he optional win-list isalist 
of window names and colors so that per-window colors may be specified. Seethe 
Bordercoior variable for a complete description of thewi n-1 i st . The default is black. 

This variable specifies the width in pixels of the border surrounding icon windows. The 
default is 2 . 

This variable specifies the directory that should be searched if a bitmap file cannot be found 
in any of the directories in thebitmapFiiePath resource. 

This variable specifies the font to be used to display icon names within icons. The default is 
variable. 

This variable specifies the foreground colorto be used when displaying icons, and may only 
be Specified inside Of a Color, Grayscale, Or Monochrome list. T he optional win - list is a 
list of window names and colors so that per-window colors may be specified. Seethe 
Bordercoior variable for a complete description of thewi n-1 i st . The default is black. 

This variable indicates that windows should be iconified by being unmapped without 
trying to map any icons. This assumes that the user will remap thewindow through the 
icon manager, thet .warpto function, ortheiwmwmdows menu. If theoptional wi n-1 i st is 
provided, only those windows will beiconified by simply unmapping. Windows that have 
both this and theiconManager Dontshow options set may not be accessible if no binding to 
the Twmwindows menu is set in the user's startup file. 

This variable specifies the background colorto useforicon manager entries, and may only 
be specified inside of a color, Grayscale, or Monochrome list. T he optional wi n- I i s t is a 
list of window names and colors so that per-window colors may be specified. Seethe 
Bordercoior variable for a complete description of the wi n-1 i st . The default iswhite. 

This variable indicates that the icon manager should not display any windows. If the 
optional wi n-1 i st isgiven, only thosewindows will not be displayed. Thisvariableisused 
to prevent windows that are rarely iconified (such asxciock or xioad) from taking up 
space in the icon manager. 
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IconManagerFont string 

IconManagerForeground 
string [{ wi n- I i st }] 


IconManagerGeometry 
string [columns ] 


IconManagerHighlight 
string [{win-list }] 


IconManagers 
{ iconmgr-list } 


IconManagerShow{ wi n- I i st 


IconRegion geomstring 
vgrav hgrav gr i dwi dt h 
gr i dhei ght 


Icons { wi n-Iist } 


This variable specifies the font to beused when displaying icon manager entries. The default 
is variable. 

This variable specifies the foreground color to beused when displaying icon manager 
entries, and may be specified only inside of a color, Grayscale, or Monochrome list. The 
optional wi n -1 i st is a list of window names and colors so that per-window colors may be 
specified. See the Bordercoiorvariablefor a complete description of the wi n -1 i st .The 
default is black. 

This variable specifiesthe geometry of the icon manager window. T he s t ri ng argument is 
standard geometry specification that indicates the initial full size oftheicon manager. The 
icon manager window is then broken intocoi umns pieces and scaled according to the 
number of entries in the icon manager. Extra entries are wrapped to form additional rows. 

T he default number of columns is i. 

This variable specifies the border color to beused when highlighting the icon manager entry 
that currently has the focus, and can only be specified inside of a color, Grayscale, or 
Monochrome list. T he optional wi n- 1 i st is a list of window names and colors so that per- 
window colorsmay be specified. Seethe Border-coiorvariablefor a complete description 
of the wi n- 1 i st . T he default isbiack. 

This variable specifies a list of icon managers to 

create. Each item in the i c on mg r -1 i st has the followi ng format: 

0 "wi n- name" [ * i conname" ] 

" g e o me t r y ” c o I u mn s 

where wi nname is the name of the windows that should be put into this icon manager, 
i conname is the name of that icon manager window's icon, geometry is a standard geometry 
specification, and col umns is the number of columns in this icon manager as described in 
Icon-ManagerGeometry. For example: 

IconManagers 

{ 

"XTerm" "=300x5+800+5" 5 
"myhost" "=400x5+100+5" 2 
} 

Clients whose name or class is XTerm will have an entry created in thexTerm icon manager. 
Clients whose name was myhost would be put into the myhost icon manager. 

> This variable specifies a list of windows that should appear in the icon manager. When used 
in conjunction with the iconManagerDontshow variable only the windows in this I ist will be 
shown in the icon manager. 

This variable specifies an area on therootwindow in which iconsare placed if no specific 
icon location is provided by the client. T he g eoms t r i ng is a quoted string containing a 
standard geometry specification. If more than one IconRegion line is given, icons will be 
put into thesucceeding icon regionswhen thefirst is full. The vgrav argument should be 
either North or south and is used to control whether icons are first filled in from the 
top or bottom oftheicon region. Similarly, thehgrav argument should be either East or 
west and isused to control whether iconsshould be filled in from the left orfrom 
the right. Icons are laid out within the region in a grid with cells g r i dwi dt h pixels wide and 
gri d h ei ght pixels high. 

This variable specifies a list of window names and the bitmap fi lenames that should be used 
as their icons For example, 

Icons 

{ 

"XTerm" "xterm.icon 11 
"xfd" “xfd_icon 11 
} 



InterpolateMenuColors 


MakeTitle { wi n-1 i s t } 
MaxWindowSize stri ng 

MenuBackground string 

MenuFont stri ng 
MenuForeground string 

MenuShadowColor stri ng 

MenuTitleBackground stri 

MenuTitleForeground stri 

Monochrome {colors } 

MoveDelta pi xel s 

NoBackingStore 

NoCaseSensitive 

NoDefaults 

NoGrabServer 
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Windows that match “XTerm 11 and would not be iconified by unmapping would try to use 
theicon bitmap in the file xterm. icon. If Forceicons is specified, thisbitmap will be used 
even if the client has requested its own icon pixmap. 

T his variable indicates that menu entry colors should be interpolated between entry 
specified colors In this example, 

Menu "mymenu" 
t 

"Title" (“ black"red 11 ) f.title 
"entryl" f.nop 
"entry2" f.nop 

"entry3" ("white":"green") f.nop 
"entry4" f.nop 

"entry5" ("red"white") f.nop 
} 

theforeground colorsfor "entryi” and "entry 2 '' will be interpolated between black and 
white and the background colors between red and green. Similarly, theforeground for 
"entry4” will behalfway between white and red, and the background will behalfway 
between green and white. 

This variable specifies a list of windows on which a title -bar should be placed and isused 
to request titles on specific windows when NoTitie has been set. 

This variable specifies a geometry in which the width and height give the maxi mum size for 
a given window. This is typically used to restrict windows to the size of the screen. The 
default width is 32767— screen width. T he default height is32767— screen height. 

This variable specifies the background color used for menus, and can only be specified 
inside Of a Color or Monochrome list. T he default iSwhite. 

This variable specifies the font to use when displaying menus. The default is variable. 

This variable specifies the foreground color used for menus and can only be specified inside 
Of a Color, Grayscale, Or Monochrome list. T he default is black. 

This variable specifies the color of the shadow behind pull-down menus and can only be 
Specified i nside Of a Color, Grayscale, Or Monochrome list. T he default is black, 
g This variable specifies the background color for t. title entries in menus, and can only be 
Specified i nside Of a Color, Grayscale, Or Monochrome list. T he default iSwhite. 
g This variable specifies the foreground color for t. title entries in menus and can only be 
specified i nside Of a Color or Monochrome list. T he default is black. 

T his variable specifies a list of color assignments that should be made if the screen has a 
depth of i. See the description of colors. 

This variable specifies the number of pixels the pointer must move before the t .move 
function starts working. Also seethet .deitastop function. The default iszero pixels. 

T his variable indicates that twm's menus should not request backing store to minimize 
repainting of menus. This istypically used with servers that can repaint faster than they can 
handle backing store. 

This variable indicates that case should be ignored when sorting icon names in an icon 
manager. Thisoption istypically used with applicationsthat capitalizethefirst letter of 
their icon name. 

This variable indicates that twm should not supply the default titlebuttons and bindings. 
Thisoption should only be used if the startup file contains a completely new set of bindings 
and definitions. 

This variable indicates that twm should not grab the server when popping up menus and 
moving opaque windows. 





Parti: User Commands 



NoHighlight [{ win-list }] 


NoIconManagers 

NoMenuShadows 


NoRaiseOnDeiconify 

NoRaiseOnMove 


This variable indicates that borders should not be highlighted to track the location of the 
pointer. If the optional wi n -1 i st is given, highlighting will only be disabled for those 
windows. When the border is highlighted, it will be drawn in the current Bordercoior. 
When the border isnot highlighted, it will be stippled with agray pattern using the current 
BorderTileForeground and BorderTileBack-ground Colors 
This variable indicates that no icon manager should be created. 

This variable indicates that menus should not have drop shadows drawn behind them. This 
is typically used with slower servers because it speedsup menu drawing at the expense of 
making the menu slightly harder to read. 

T his variable indicates that windows that are deiconified should not be raised. 
Thisvariableindicates that windows should not be raised when moved. This is typically 
used to allow windows to slide underneath each other. 


NoRaiseonResize This variable indicates that wi ndows should not be raised when resized. T his is typically 

used to allow windows to be resized underneath each other. 


NoRaiseonwarp T his variable indicates that windows should not be raised when the pointer is warped into 

them with thet .warpto function. If thisoption is set, warpingto an occluded window may 
result in the pointer ending up in the occluding window instead the desired window, which 
causes unexpected behavior with f .warpring. 

Nosaveunders T his variable indicates that menus should not request save-understo minimize window 

repainting following menu selection. It istypically used with di splays that can repaint faster 
than they can handle save-unders. 

NostackMode [{win-iist >] T his variable indicates that client window requests to change stacking order should be 

ignored. If the optional wi n -1 i st is given, only requests on those windows will beignored. 
This is typically used to prevent applications from relentlessly popping themselves to the 
front of the wi ndow stack. 


NoTitle [{ wi n-Iist }] 


NoTitleFocus 


NoTitleHighlight 
[{ wi n- I i s t }] 


OpaqueMove 


Pixmaps { pi xma ps } 


Priority priority 


RandomPlacement 


Thisvariableindicates that windows should not have title-bars. If theoptional wi n -1 i st is 
given, only those windows will not have titlebars. MakeTitie may be used with thisoption 
to force titlebars to be put on specific windows. 

This variable indicates that twm should not set keyboard input focus to each window as it is 
entered. N ormally, twm sets the focus so that focus and key a/entsfrom the titlebar and icon 
managers are delivered to the application. If the pointer is moved quickly and twm is slow to 
respond, input can bedirected to theold window instead of the new. Thisoption is 
typically used to prevent thisinput lag and to work around bugs in older applications that 
haveproblemswith focus events. 

Thisvari ableindicates that thehighlight area of thetitlebar, which isused to indicate the 
window that currently has the input focus, should not be displayed. If theoptional wi n- 
i i st is given, only those windowswill nothavehighlightareas.ThisandthesqueezeTitie 
optionscan be set to substantially reduce the amount of screen space required by titlebars. 
This variable indicates that the t. move function should actually move thewindow instead of 
just an outline so that the user can immediately see what the window will look like in the 
new position. Thisoption istypically used on fast d i sp I ay s (p arti cu I ar I y if NoGrabserver is 
set). 

This variable specifies a list of pixmaps that define the appearance of various images. Each 
entry is a keyword indicating thepixmap to set, followed by a string giving the name of the 
bitmap file. T he following pixmaps may be specified: 0 Pixmaps { mieHighiight 

"grayl“ } 

The default for TitieHighiight isto use an even stipple pattern. 

This variable sets twm's priority, priority should bean unquoted, signed number (for 
example, 999 ). This variable has an effect only if the server supports the SYN C extension. 
This variable indicates that windows with no specified geometry should be placed in a 
pseudorandom location instead of having theuser drag out an outline. 



ResizeFont string 

RestartPreviousState 

SaveColor { colors-list 


ShowIconManager 

SortlconManager 

SqueezeTitle 
[{ s queeze- list }] 


Startlconified 
[{ wi n- I i s t }] 


TitleBackground string 
[{ wi n- I i s t }] 

TitleButtonBorderWidth 

pi xel s 
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This variable specifiesthe font to beused forin the dimensionswindow when resizing 
windows. The default is fixed. 

This variable indicates that twm should attempt to usethewM_sTATE property on client 
windows to tell which windows should beiconified and which should be left visible This is 
typically used to try to regenerate the state that the screen was in before the previous 
window manager was shutdown. 

This variable indicates a list of color assignments to be stored as pixel values in the root 
window property _mit_priority_colors. Clients may elect to preserve these values when 
installing their own colormaps. Note that use of this mechanism isawayforan application 
to avoid the "technicolor" problem, whereby useful screen objects such as window borders 
and titlebars disappear when a program's custom colors are installed by the window 
manager. For example 
SaveColor 
{ 

BorderColor 
TitleBackground 
TitleForeground 
" red" 

"green" 

"blue" 

} 

This would pi ace on the root window three pixel values for borders and titlebars, as well as 
thethree color strings, all taken from the default colormap. 

This variable indicates that the icon manager window should be displayed when twm is 
started. It can always be brought up using the f.showiconmgr function. 

This variable indicates that entries in the icon manager should be sorted alphabetically 
rather than by simply appending new windows to the end. 

Thisvariable indicates that twm should attempt to usethesHAPE extension to maketitlebars 
occupy only as much screen space as they need, rather than extending all the way across the 
top of the window. The optional squeeze -1 i st may beused to control the location of the 
squeezed titlebar along the top of the window. It contains entries of the form: 0 ■ name" 
justification numdenom where n a me is a window name, justification is either left, 
center, or right, and n u m and d e no m are numbers specifying a ratio giving the relative 
position about which the titlebar is justified. The ratio is measured from left to right if the 
numerator is positive, and right to left if negative. A denominator of 0 indicates that the 
numerator should be measured in pixels. For convenience, the ratio 0/0 is the same as 1/2 
for center and - 1/1 for right. For example, 

SqueezeTitle { "XTerm" left 0 0 "xterml" left 1 3 "xterm2" left 2 3 
"oclock" center 0 0 "emacs" right 00} 

T he DontsqueezeTitie list can beused to turn off squeezing on certain titles. 
Thisvariableindicates that client windows should initially be left asiconsuntil explicitly 
deiconified bytheuser. If theoptional wi n -1 i st is given, only thosewindows will be 
started iconic. This is useful for programs that do not support an -iconic command-line 
option or resource. 

This variable specifies the background color used in titlebars, and may only be specified 
inside Of a Color, Grayscale, Or Monochrome list. T he optional win-list isalistof window 
names and colors so that per-window colors may be specified. The default iswhite. 

This variable specifiesthe width in pixels of the border surrounding titlebuttons. This is 
typically set to 0 to allow titlebuttons to take up as much space as possible and to not have a 
border. The default is 1. 
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TitleFont st ri ng 

TitleForeground stri ng 
[{ wi n- I i s t }] 

TitlePadding pixels 

Unknownlcon stri ng 

UsePPosition stri ng 


WarpCursor [{ win-list }] 


WindowRing { wi n-Iist } 
WarpUnmapped 


XorValue number 


Zoom [count ] 


This variable specifies the font to be used for displaying window names in titlebars. The 
default is variable. 

This variable specifies the foreground color used in titlebars, and may only be specified 
inside Of a Color, Grayscale, Or Monochrome list. T he optional win-list isalistof window 
names and colors so that per-window colors may be specified. The default is black. 

T his variable specifies the distance between the various buttons, text, and highlight areasin 
thetitlebar. The default is 8 pixels. 

This variable specifies the filename of a bitmap file to be used as the default icon. This 
bitmap will be used as the icon of all clients that do not provide an icon bitmap and are not 
listed in the icons list. 

This variable specifies whether or not twm should honor program-requested locations (given 
by the pposition flag in thewM_NORMAL_HiNTs property) in the absence of a user-specified 
position. The argument stri ng may have one of three values: off (the default), indicating 
that twm should ignore the program-supplied position; on, indicating that the position 
should be used; and non-zero, indicating that the position should used if it is other than 
(0,0). The latter option is for working around a bug in older toolkits 
Thisvariableindicatesthatthepointer should be warped into windowswhen they are 
deiconified. If the optional wi n - 1 i st is given, the pointer will only be warped when those 
windows are deiconified. 

This variable specifies a list of windows along which the f .warpring function cycles. 

T his variable indicates that the f.warpto function should deiconify any iconified windows 
it encounters. This is typically used to make a key binding that will pop up a particular 
window (such asxmh) no matter where it is. The default is for f.warpto to ignore iconified 
windows. 

This variable specifies the value to use when drawing window outlines for moving and 
resizing. This should be set to a value that will result in a variety of distinguishable colors 
when exclusive or isused with the contents of the user's typical screen. Setting this variable 
to 1 often gives nice results if adjacent colors in the default colormap are distinct. By 
default, twm will attempt to cause temporary lines to appear at the opposite end of the 
colormap from the graphics 

This variable indicates that outlines suggesting movement of awindow to and from its 
iconified state should be displayed whenever awindow isiconified or deiconified. The 
optional count argument specifies the number of outlines to be drawn. The default count 
is 8. 


The following variables must beset after the fonts have been assigned, so it is usually best to put them at the end of the 
variables or at the beginning of the bindings sections: 

DetauitFunction f unct i on This variable specifies the function to be executed when a key or button event isreceived for 
which no binding is provided. This is typically bound tot .nop, t .beep, or a menu 
containing window operations. 

wmdowFunction f unct i on This variable specifies the function to execute when awindow is selected from the 

Twmwindows menu. If thisvariableisnotset, thewindow will be deiconified and raised. 


BINDINGS 

After the desired variables have been set, functions may be attached titlebuttonsand key and pointer buttons. Titlebuttons 
may be added from the left or right side and appear in thetitlebar from left to right according to the order in which they are 
specified. Key and pointer button bindings may be given in any order. 

Titlebuttons' specifications must include the name of the pixmap to use in the button box and the function to be invoked 
when a pointer button is pressed within them: 
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0 LeftTitleButton "bi t mapname "=f unct i on 

or 

0 RightTitleButton "bi tmapname"=funct i on 

T he b i t mapname may refer to one of the built-in bitmaps (which are scaled to match Title-Font) by using the appropriate 
colon-prefixed namedescribed earlier. 

Key and pointer button specifications must givethe modifiersthat must be pressed, over which parts of the screen the 
pointer must be, and what function isto be invoked. Keys are given as strings containing the appropriate keysym name; 
buttons are given as the keywords Buttonl-Buttons: 0 ■FP1 m = modi i st : context : function Buttonl = modi i st : 
cont ext : function 

T he mo d 1 i s t is any combination of the modifier names shift, control, lock, meta, modi, mod 2 , mod3, mod4, or mods (which 
may be abbreviated ass, c, 1, m, mi, m 2 , m3, m4, ms, respectively) separated by a vertical bar (|). Similarly, the c o nt ext isany 
combination of window, title, icon, root, frame, iconmgr, their first letters (iconmgr abbreviation ism), or ail, separated 
by a vertical bar. The function is any of the f keywords described in thefollowing list. For example, the default startup file 
contains the following bindings: 

Buttonl = : root : f.menu "TwmWindows" 

Buttonl = m : window | icon : f. function "move-or-lower" 

Button2 = m : window [ icon : f.iconify 

Button3 = m : window | icon : f.function "move-or-raise" 

Buttonl = : title : f.function "move-or-raise" 

Button2 = : title : f.raiselower 

Buttonl = : icon : f.function "move-or-iconify" 

Button2 = : icon : f.iconify 
Buttonl = : iconmgr : f.iconify 
Button2 = : iconmgr : f.iconify 

A user who wanted to be able to manipulate windows from the keyboard could use the following bindings: 


"FI" = 


all 

: f.iconify 

" F2" = 


all 

: f.raiselower 

" F3" = 


all 

: f.warpring "next" 

" F4" = 


all 

: f.warpto "xmh" 

" F5" = 


all 

: f.warpto "emacs" 

" F6" = 


all 

: f.colormap "next" 

" F7" = 


all 

: f.colormap "default" 

" F20" 


all 

: f.warptoscreen "next" 

"Left" 

= 

m : 

all : f.backiconmgr 

"Right 


m 

s : all : f.forwiconmgr 

"Up" = 

m 

: all : f.upiconmgr 

"Down" 

= 

m j 

s : all : f.downiconmgr 


twm provides many more window manipulation primitives than can be conveniently stored in a titlebar, menu, or set of key 
bindings. Although a small set of defaults is supplied (unless the NoDetauits is specified), most users will want to have their 
most common operations bound to key and button strokes. To do this, twm associates names with each of theprimitivesand 
provides user-defined functions for building higher level primitives and menus for interactively selecting among groups of 
functions. 
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User-defined functions contain the name by which they are referenced in calls to f. function and a list of other functions to 
execute. For example, 


Function "move-or-lower" { f.move f.deltastop f.lower } 

Function "move-or-raise" { f.move f.deltastop f.raise } 

Function "move-or-iconify" { f.move f.deltastop f.iconify } 

Function "restore-colormap" { f.colormap "default" f.lower } 

The function name must be used in t .function exactly as it appears in the function specification. 


In the followi ng descriptions, if thefunction is said to operate on the selected window, butisinvoked from arootmenu, the 
cursor will be changed to the Select cursor and the next window to receive a button press will be chosen: 


! string 
f.autoraise 

f.backiconmgr 

f.beep 

f.bottomzoom 

f.circledown 
f.circleup 
f.colormap s t r i ng 


f.deiconify 

f.delete 


f.deltastop 

f .destroy 

f.downiconmgr 
f.exec s t r i ng 

f .focus 


T his is an abbreviation for f. exec string. 

This function toggles whether or not the selected window is raised whenever entered by the 
pointer. Seethedescription of the variable AutoRaise. 

This function warps the pointer to the previous column in the current icon manager, 
wrappi ng back to the previous row if necessary. 

This function sounds the keyboard bell. 

T his function is si mi lar to the f. f uiizoom fundi on, but resizes the wi ndow to fill only the 
bottom half of thescreen. 

This function lowers the topmost window that occludes another window. 

This function raises the bottommost window that is occluded by another window. 

This function rotates the colormaps (obtained from thewM_coi_oRMAP_wiNDows property on 
the window) that twm will display when the pointer is in this window. The argument 
string may have one of the following values: next, prev, and default. It should be noted 
here that in general, the installed colormap isdetermined by keyboard focus. A pointer- 
driven keyboard focus will install a private colormap upon entry of the window owning the 
colormap. Using the cl ick-to-type model, private colormaps will not deinstalled until the 
user clicks on the target window. 

This function deiconifies the selected window. If the window is not an icon, this function 
does nothing. 

This function sends the wm_delete_window message to the selected window if the client 
application has requested itthrough thewM_PROTocoi_s window property. Theapplication is 
supposed to respond to the message by removing the indicated window. If the window has 
not requested wm_delete_window messages, the keyboard bell will be rung, indicating that 
the user should choose an alternative method. N ote this is very different from f. destroy. 

T he intent here is to delete a single window, not necessarily the entire application. 
Thisfunction allows a user-defined function to be aborted if the poi nter has been moved 
more than MoveDeita pixels. See the example defi ni tion given for Function “move-or- 
raise " at the beginning of the section. 

Thisfunction instructs the x server to close the display connection of the client that created 
the selected window. This should only be used as a last resort for shutting down runaway 
clients. See also f. delete. 

Thisfunction warps the pointer to the next row in the current icon manger, wrapping to 
the beginning of the next column if necessary. 

Thisfunction passes the argument string to /bin/sh for execution. In multiscreen mode, 
if st r i ng starts a new x client without giving a display argument, the client will appear on 
thescreen from which thisfunction wasinvoked. 

This function toggles the keyboard focus of the server to the selected window, changing the 
focus rule from pointer-driven if necessary. If the selected window already was focused, this 
function executes an f. untocus. 



f.forcemove 
f.forwiconmgr 

f.fullzoom 

f .function s t r i ng 

f.hbzoom 
f.hideiconmgr 
f.horizoom 

f.htzoom 
f.hzoom 
f.iconify 
f.identify 

f.lefticonmgr 
f.leftzoom 

f.lower 
f .menu st r i ng 

f.move 


f.nexticonmgr 
f. nop 

f.previconmgr 
f .priority s t r i ng 

f .quit 

f.raise 
f.raiselower 

f.refresh 
f.resize 

f.restart 
f.righticonmgr 
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Thisfunction is like f .move except that it ignores the DontMoveott variable. 

Thisfunction warps the pointer to the next column in thecurrent icon manager, wrapping 
to the beginning of the next row if necessary. 

Thisfunction resizes the selected window to the full size of the display or else restores the 
original size if the window was already zoomed. 

Thisfunction executes the user-defined function whose name is specified by the argument 

s t r i n g. 

This function is a synonym for t. bottomzoom. 

This function unmaps the current icon manager. 

This variable is similar to the t. zoom function except that the selected window is resized to 
the full width of the display. 

Thisfunction is a synonym fort .topzoom. 

This function is a synonym for t. horizoom. 

Thisfunction iconifiesor deiconifies the selected window or icon, respectively. 

Thisfunction displays a summary of the name and geometry of the selected window. If the 
server su pports th e sync exten sion, the priority of the client owning the window is also 
displayed. Clicking the pointer or pressing a key in the window will dismiss it. 

T his function is simi lar to f. backiconmgr except that wrapping does not change rows. 

T his variable is si mi lar to the t. bottomzoom function but causes the selected wi ndow to be 
resized only on the left half of the display. 

Thisfunction lowers the selected window. 

Thisfunction invokes the menu specified by theargumentstri ng. Cascaded menusmay be 
built by nesting cal Is to t. menu. 

Thisfunction drags an outlineof theselected window (or the window itself if the 
opaqueMove variable is set) until the invoking pointer button is released. Double-clicking 
within the number of milliseconds given by const rainedMoveTime warps the pointer to the 
center of the window and constrains the move to be either horizontal or vertical, depending 
on which grid line is crossed. T o abort a move, press another button before releasing the 
first button. 

Thisfunction warps the pointer to the next icon manager containing any windows on the 
current or any succeedi ng screen. 

Thisfunction does nothing and is typically used with the Default-Function or 
windowFunction variables or to introduce blank linesin menus. 

This function warps the pointer to the previous icon manager containing any windows on 
thecurrent or preceding screens. 

Thisfunction sets the priority of theclient owning the selected window to the numeric 
value of the argument s t r i ng, which should be a signed integer in double quotes (for 
example, " 999 "). Thisfunction has an effect only if the server supports the sync extension. 
Thisfunction causes twm to restore the window's borders and exit. If twm isthefirst client 
invoked from xdm, thiswill result in a server reset. 

Thisfunction raises the selected window. 

Thisfunction raises the selected window to the top of the stacking order if it is occluded by 
any windows; otherwise, thewindow islowered. 

Thisfunction causes all windows to be refreshed. 

Thisfunction displays an outlineof theselected window. Crossing a border (or setting 
AutoReiativeResize) will cause the outlineto begin to rubber band until the invoking 
button isreleased. T 0 abort a resize, press another button before releasing the first button. 
Thisfunction kills and restarts twm. 

T his function is simi lar to f. nexticonmgr except that wrappi ng does not change rows. 
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f.rightzoom 
f.saveyourself 


f.showiconmgr 
f.sorticonmgr 

f.title 

f. topzoom 

f.unfocus 

f.upiconmgr 

f.vlzoom 
f.vrzoom 

f .warpring st ri ng 
f .warpto s t ri n g 


f.warptoiconmgr string 


f .warptoscreen string 


f.winrefresh 

f.zoom 


This variable is similar to the f.bottomzoom function except that the selected window is 
only resized to the right half of the display. 

This function sends a wm_saveyourself message to the selected window if it has requested 
themessagein its wm_protocols window property. Clients that accept this message are 
supposed to checkpoint all states associated with thewindow and update thewM_coMMAND 
property as specified in the icccm. If the selected window has not been selected for this 
message, the keyboard bell will be rung. 

Thisfunction maps the current icon manager. 

Thisfunction sorts the entries in the current icon manager alphabetically. See the variable 
SortlconManager. 

Thisfunction provides a centered, un selectable item in a menu definition. It should not be 
used in any other context. 

This variable is similar to the f.bottomzoom function except that the selected window is 
only resized to the top half of the display. 

Thisfunction resets the focus back to pointer-driven. This should be used when a focused 
window isno longer desired. 

Thisfunction warps the pointer to the previous row in the current icon manager, wrapping 
to the last row in the same column if necessary. 

This function is a synonym for t. let tzoom. 

This function is a synonym for f. rigbtzoom. 

Thisfunction warps the pointer to the next or previous window (asindicated by the 
argument st r i ng, which may be "next" or "prev") specified in thewindowRing variable. 
Thisfunction warps the pointer to thewindow that hasa nameor class that matches 
stri ng. If thewindow is iconified, it will bedeiconified if thevariablewarpunmapped is set 
or else ignored. 

T his function warps the pointer to the icon manager entry associated with thewindow 
containing the pointer in the icon manager specified bytheargumentstri ng. Ifstri ng is 
empty (that is, "“), thecurrent icon manager ischosen. 

Thisfunction warps the pointer to the screen specified by the argument st r i ng. st r i ng 
may be a number (such as'V' or "i"), the word ■ next" (indicating the current screen plus 
1, skipping over any unmanaged screens), the word "back" (indicating the current screen 
minus 1, skipping over any unmanaged screens), or the word ■ prev (indicating the last 
screen visited. 

This function is simi lar to the f. refresh function except that only the selected window is 
refreshed. 

Thisfunction is simi lar to thef .fuiizoom function, except that only the height of the 
selected window is changed. 


MENUS 

Functionsmay be grouped and interactively selected using pop-up (when bound to a pointer button) or pull-down (when 
associated with atitlebutton) menus. Each menu specification contains the name of the menu as it will be referred to by 
f .menu, optional default foreground and background colors the list of item names and the functions they should invoke, 
and optional foreground and background colors for individual items: 

Menu "menuname"[("deff ore":" defback") ] { stringl [("forel": "backn")] functionl stri n g 2 
[ ("f o r e 2": "backn") ] function2 ...stringN [ ("f or eN ": "backN ") ] functionN } 

The menuname i s case-sen si ti ve. T he optional deff ore and defback arguments specify the foreground and background colors 
used on a color display to highlight menu entries. The string portion of each menu entry will be the text that will appear in 
the menu. The optional fore and back arguments specify the foreground and background colors of the menu entry when the 
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pointer is not in the entry. These colors will only be used on a color display. The default is to use the colors sped tied by the 
MenuForeground and MenuBackground variables. T he function portion of the menu entry is one of the functions including 
any user-defined functions, or additional menus. 

There is a special menu named Twmwindows that contains the names of all of the client and twm-supplied windows. Selecting 
an entry will cause the windowFunction to be executed on that window. If windowFunction hasn't been set, the window will 
bedeiconified and raised. 

ICONS 

twm supports several different ways of manipulating iconified windows. T he common pixmap-and-text style may be laid out 
by hand or automatically arranged as described by theiconRegion variable. In addition, a terse grid of icon names, called an 
icon manager, provides a more efficient use of screen space as well as the ability to navigate among windows from the 
keyboard. 

An icon manager is a window that contains names of selected windows or all windows currently on the display. In addition 
to the window name a small button using the default iconify symbol will be displayed to the left of the name when the 
window is iconified. By default, clicking on an entry in the icon manager performst .iconify. T o change the actions taken 
in theicon manager, usetheiconmgr context when specifying button and keyboard bindings. 

If you move the pointer into theicon manager, the keyboard focus is also directed to theindicated window (setting the focus 
explicitly Or else sending synthetic events NoTitleFocus is set). U si ng the f . upiconmgr, f. downiconmgr, f . lef ticonmgr, 
and f. rignticonmgn functions the input focus can be changed between windows directly from the keyboard. 

BUGS 

The resource manager should have been used instead of all of thewindow lists. 

T he iconRegion variable should take a list. 

Double-clicking very fast to get the constrained move function will sometimes cause thewindow to move, even though the 
pointer is not moved. 

If IconifyByUnmapping is On and windows are listed i n IconManagerDontShow but not in Dont Iconif yByUnmapping, they 
may be lost if they are iconified and no bindings to f .menu ■ Twmwindows" orf .warpto are setup. 

FILES 

$H0ME/.twmrc.<screen number> 

$HOME/.twmrc 

<XRoot>/lib/X11/twm/system.twmrc 

ENVIRONMENT VARIABLES 

display This variable is used to determine which x server to use. It is also set during f .exec so that programs come up on 
the proper screen. 

home This variable is used as the prefix for files that begin with a tilde and for locating the twm startup file. 

SEE ALSO 

x(l), Xserver(l), xdm(l), xrdb(l) 

AUTHORS 

Tom LaStrange, SolbourneComputer; Jim Fulton, M IT X Consortium; StevePitschke, Stardent Computer; Keith Packard, 
M IT X C onsortium; D ave Payne, Apple C omputer. 

SEE ALSO 

X(l), Xserver(l), x 


X Vera on 11 Released 
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txt2gcal 

txt 2 gcai— Creates a verbatim gcai resource file from a text file 

SYNOPSIS 

txt2gcal [ --help | --version ] | [ Text-file | - ] [Dat e-part ] 

DESCRIPTION 

txt 2 gcai is a program that creates a verbatim gcai resource file from a text file. If no t ext - f i i e or - argument is given, the 
program reads and processes all input received from the standard input channel. If no date - part argument isgiven, 
txt 2 gcai creates a 0 for the date part. All results are always shown on the standard output channel. An exit status of 0 means 
all processing is successfully done; any other value means an error has occurred. 

OPTIONS 

--help Print a usage message listing all available options then exit successfully. 

--version Print the version number, then exit successfully. 

COPYRIGHT 

Copyright© 1996 Thomas Esken. This software doesn't claim completeness, correctness, or usability. On principle, I will not 
be liable for any damages or losses (implicit or explicit), which result from using or handling my software. If you use this 
software, you agree without any exception to this agreement, which binds you legally. 

txt 2 cai is free software and distributed under the terms of theGN U General Public License; published by the Free Software 
Foundation; version 2 or (at your option) any later version. 

Any suggestions, improvements, extensions, bug reports donations, proposals for contract work, and so forth are welcome. If 
you likethistool, I'd appreciate a postcard from you! 

Enjoy it =6") 

AUTHOR 

T homas Esken (esken@uni-muenster.de) 
m FI agenfeld 84 
D-48147 M uenster; Germany 
Phone:+49 251 232585 

SEE ALSO 

gcal(l), tcal(l) 

16 July 1996 
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ul— Do underlining 

SYNOPSIS 

ul [ - i] [-t terminal] [name ...] 

DESCRIPTION 

ui reads the named files (or standard input if none are given) and translates occurrences of underscores to the sequence that 
indicates underlining for the terminal in use, as specified by the environment variable term . The file /etc/ter-mcap is read to 
determine the appropriate sequences for underlining. If the terminal is incapable of underlining but is capable of a standout 
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mode then that is used instead. If the terminal can overstrike or handles underlining automatically, ui degenerates to 
cat(l). If the terminal cannot underline, underlining is ignored. 

The following options are available: 

-i U nderlining is indicated by a separate line containing appropriate dashes this is useful when you want to 

look at the underlining which is present in an nroft output stream on a CRT terminal. 

-t terminal Overrides the terminal type specified in the environment with terminal. 

ENVIRONMENT 

T he following environment variable is used 

term Relates a tty device with its device capability description; see termcap(5). term is set at login time, either 

by the default terminal type specified in /etc/ttys or asset during the login process by the user in the 
login file; seesetenv(l). 

SEE ALSO 

man(l), nroff(l), colcrt(l) 

BUGS 

nroft usually outputs a series of backspaces and underlines intermixed with the text to indicate underlining. N o attempt is 
made to optimize the backward motion. 

HISTORY 

T he ui command appeared in BSD 3.0. 

BSD 4, 6Junel993 
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unexpand— Convert spaces to tabs 

SYNOPSIS 

unexpand [-tabl [ ,ta b 2 [,...]] ] [ -t tabl [ ,ta b 2 [,...]] ] [-a][--tabs=t abl [ ,ta b 2 [,...]]] 

[••all] [--help] [--version] [file...] 

DESCRIPTION 

This manual page documents the GN U version of unexpand, unexpand writes the contents of each given file or the standard 
input if none are given or when a file named - is given, to the standard output, with strings of two or more space or tab 
characters converted to asmany tabs as possible foil owed by as many spaces as are needed. By default, unexpand converts 
only initial spaces and tabs (those that precede all characters that aren't spaces or tabs) on each line. It preserves backspace 
characters in the output; they decrement the column count for tab calculations. By default, tabs are set at every 8th column. 

OPTIONS 

-t, --tabs t abi [ ,t ab2 [,... ]] If only one tab stop isgiven, set the tabs t a b 1 spaces apart i nstead of the default 8. 

Otherwise, set the tabs at columns t abi, t a b2 , and so on (numbered from 0) and 
leave spaces and tabs beyond the tab stops given unchanged. If thetab stops are 
specified with the -t or - - tabs option, they can be separated by blanks as well as by 
commas. This option impliesthe -aoption. 

-a, - - an Convert all strings of two or more spaces or tabs, not just initial ones, to tabs. 

- - help Print a usage message and exit with a non-zero status. 

--version Print version information on standard output, then exit. 


GNU Text Utilities 
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uniq 

uniq— Remove duplicate linesfrom a sorted file 

SYNOPSIS 

uniq [-cdu] [-f skip-fields] [-s skip-chars] [-w check-chars] [-#skip-fields] 

[+#skip-chars] [--count] [--repeated] [--unique] [--skip-fields=skip-fields] 

[--skip-chars=skip-chars] [--check-chars=check-chars] [--help] [--version] 

[infile] [outfile] 

DESCRIPTION 

This manual page documents the GN U version of uniq. uniq prints the unique lines in asorted file, discarding all butoneof 
arun of matching lines. Itcan optionally show only lines that appear exactly once or lines that appear more than once, uniq 
requires sorted input because it compares only consecutive lines. 

If the output fi le is not specified, uniq writes to the standard output. I f the i nput fi le is not specified, it reads from the 
standard input. 

OPTIONS 

-u, - -unique 
-d, --repeated 
-c, - -count 
-number , -f, 

- - skip-fields=number 


+n umber , -s, 

--skip-chars=number 

-w, 

--check-chars=number 
--help 
--version 


unshar 

unshar — U npack a shar file 

SYNOPSIS 

unshar [ -d directory ] [ -c ][-e J -E exit_line ] [file ... ] 

DESCRIPTION 

unshar scans mail messages looking for the start of a shell archive. It then passes the archive through a copy of the shell 
to unpack it. It will accept multiple files. If no files are given, standard input is used. This manual page reflects unshar 
version 4.0. 


Only print unique lines 
Only print duplicate lines 

Print the number of times each line occurred along with the line 
In this option, number is an integer representing the number of fields to skip over 
before checking for uniqueness. The first number fields, along with any blanks 
found beforenumber fields is reached, are skipped over and not counted. Fields are 
defined as a strings of nonspace, nontab characters that are separated from each 
other by spaces and tabs. 

In this option, number is an integer representing the number of characters to skip 
over before checking for uniqueness. The first number characters, along with any 
blanks found before number characters is reached, are skipped over and not counted. 

If you use both the field and character skipping options, fields are skipped over first. 

Specify the number of characters to compare in the lines, after skipping any specified fields 
and characters. N ormally, the entire remainder of the lines are compared. 

Print a usage message and exit with a non-zero status. 

Print version information on standard output, then exit. 

GNU Text Utilities 
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561 


OPTIONS 

Optionshavea one-letter version starting with - ora long version starting with The exceptions are --help and -- 
version, which don't have a short version. 


--version 
--help 

-d Dl RECTORY 
--directory=DI RECTORY 
-c --overwrite 


-e --exit-0 


-E STRI NG 
--split-at=STRI NG 


Print the version number of the program on standard output, then immediately exit. 

Print a help summary on standard output, then immediately exit. 

Change directory to Dl RECTORY 
before unpacking any files. 

Passed as an option to theshar file. M any shell archive scripts (including those produced by 
shar 3.40 and newer) accept a -c argumentto indicate that existing fi les should be 
overwritten. 

This option exists mainly for people who collect many shell archives into a single mail 
folder. With thisoption, unshar isolates each different shell archive from the others that 
have been put in the same file, unpacking each in turn, from the beginning of the file 
towards its end. Its proper operation relies on thefact that many shar files are terminated 
by an exit oat the beginning of aline. 

Option -e isinternally equivalent to -e "exit 0 ". 

Thisoption works like -e, but it allows you to specify the string that separates archives 
if exit 0 isn't appropriate. For example noticing that most .signatures havea -- 
on a line right before them, one can sometimes use - - split-at=-- for splitting shell 
archives that lack the exit 0 line at end. The signature will then be skipped altogether with 
the headers of the following message. 


SEE ALSO 

shar(l) 

DIAGNOSTICS 

Any message from the shell may be displayed. 


AUTHORS 

M ichael M auldin at Carnegie-M ellon University, Guido van Rossum at CWI, Amsterdam (guido@mcvax), Bill Davidsen 
(davidsen@sixhub.uuxp), Warren TUCker (wht%n4hgf@gatech.edu) 

Richard H. Gumpertz (rhg@cps.coM), and Colas Nahaboo (coias@avahi.inria.tr). M an pages by Jan Djfrv 
(jhd@irfu.se). 

12 August 1990 


updatedb 

updatedb— U pdate a filename database 

SYNOPSIS 

updatedb [options] 

DESCRIPTION 

This manual page documents the GN U version of updatedb, which updates filename databases used by GN U locate. The 
filename databases contain lists of files that were in particular directory trees when the databases were last updated. The 
filename of the default database is determined when locate and updatedb are configured and installed. The frequency with 
which the databases and the directories for which they contain entries are updated depends on how often updatedb is run, 
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and with which arguments. In networked environments it often makes sense to build a database at the root of each 
filesystem, containing the entries for that filesystem. T o prevent thrashing the network, updatedb is then run for each 
filesystem on the fileserver where that filesystem ison alocal disk. Users can select which databases locate searches using an 
environment variable or command-line option; seeiocate(lL). Databases can not be concatenated together. The filename 
database format changed starting with GNU find and locate version 4.0 to allow machines with different byte orderings to 
share the databases. The new GNU locate can read both the old and new database formats. H owever, old versions of 
locate and find produce incorrect results if given a new-format database. 

OPTIONS 

--localpaths='path1 pat h2 ... 1 
--netpaths='pat hi pat h2 .. .' 

--prunepaths='path1 pat h2 ... ' 

--output=dbf i I e 

--netuser=us er 
--old-format 

- - version 

- -help 

SEE ALSO 

find(lL), locate(lL), iocatedb(5L), xargs(lL) Finding Files (online in info, or printed) 

uptime 

uptime— Tell how long the system has been running 

SYNOPSIS 

uptime 

DESCRIPTION 

uptime gives a one-li ne display of the information that follows it: the current time how longthesystem has been running, 
how many users are currently logged on, and the system load averages for the past 1, 5, and 15 minutes. 

This is the same information contained in the header linedisplayed by w(l). 

FILES 

/var'/run/utmp Information about who is currently logged on 
/proc Process information 

AUTHORS 

uptime was written by Larry G reenfield (greenf ie@gauss. rutgers. edu) and M ichael K. J ohnson 
(j ohnsonmOsunsite. unc. edu). 

SEE ALSO 

ps(l), top(l), utmp(5), w(l) 


N onnetwork directories to put in the database. D efault is/. 

N etwork (nfs, afs, rfs, and so on) directories to put in the database. Default is 
none. 

D i rectori es to not put in thedatabase, which would otherwise be put there. Default 
is/tmp /usr/tmp /var/tmp /afs. 

The database file to build. Default is system-dependent, but typically /usr/local/ 
var/locatedb. 

The user to search network directories as, using su(l). Default is daemon. 

Create the database in the old format instead of the new one. 

Print the version number of updatedb and exit. 

Printasummary of theoptionsto updatedb and exit. 


Cohesive Systems 26 January 1993 
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userlist 

useriist— User listing of who's on your system 

SYNOPSIS 

userlist 

DESCRIPTION 

This program simply gives you a listing of who is connected to your system. It is used primarily in the sorted listing that 
utilitizes the same method of display for a more uniform output between systems. It also made more sense to do itthisway 
instead of having jumbled up display listings in sorted finger displays. Besides, it made more sense to do this than use 

finger. :) 

Thisprogram functions with thesametypesofthingsin mind thatcfingerd does. If theuser hasa .nofinger file, his or her 
usernamewill not bedisplayed in theuser listing. 

Example output isshown as 

Username Real Name Idletime TTY Remote console username I'm real ... 9d 23:59 0 
(remote.site.com) 

where it would display the user's login name, the user's real name, the user's idle time given in the format "dd hh: mm”, the 
tty, and the remote location (or where the user is telnetting from). 

If the username is more than a certain number of characters, the program will not search for their information in thepasswd 
file because it may be too long. Besides, it checks getpwnam, anyway. 

CONTACTING 

If you like this program, have any suggestions on how itcould be modified, or have bug reports, please write to 
khollis@bitgate.com. 

Your continued public domain support is appreciated! Thanks. 

SEE ALSO 

cf ingerd .conf( 5 ), cfingerd( 8 ), finger(l) 

UsrtiiO.O.l, 26Augustl995 


UUCP 

UUCP- UNIX-to-UNIX copy 

SYNOPSIS 

uucp [ options ] source-file desti nati on-fiI e 

uucp [ options ] source-fiI e.., desti nati on-di rectory 

DESCRIPTION 

The uucp command copies files between systems. Each file argument is either a pathname on the local machine or is of the 
form 

syst em! pat h 

which is interpreted as being on a remote system. In the first form, the contents of the first file are copied to the second. In 
thesecond form, each sourcefileiscopied into thedestination directory. 
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A file be transferred to or from s y s t e m 2 via s y s t e mi by using 
s y s t e ml! s y s t e m2! p a t h 

Any pathname that does not begin with / or' will be appended to the current directory (unless the -wor - -noexpand option 
is used); this resulting path will not necessarily exist on a remote system. A pathname beginning with a simple~ starts at the 
uucp public directory; a pathname beginning with “name starts at the home directory of the named user. The' is interpreted 
on the appropriate system. N otethat some shells will interpret a simple “ to the local home directory before uucp sees it; to 
avoid this, the “ must be quoted. 

Shell metacharacters? * [ ] are interpreted on the appropriate system, assuming they are quoted to prevent the shell from 
interpreting them first. 

The copy does not take place immediately, butisqueued upfortheuucico(8) daemon; thedaemon is started immediately 
unless the -r or - -nouucico switch is given. In any case, the next time the remote system is called, the file(s) will be copied. 


OPTIONS 


T he followi ng options may be given to uucp. 


-c, - -nocopy 


-C, - -copy 
-d, --directories 
-f, --nodirectories 
-g gr ade, - -grade gr ade 

-m, - -mail 

-n user, - -notify user 
-r, - -nouucico 
-j, -- j obi d 


-W, --noexpand 
-x type, - -debug t y pe 


-I file, --config file 

-v, --version 
--help 


Do not copy local source files to the spool directory. If they are removed before being 
processed by theuucico(8) daemon, the copy will fail. The files must be readable by the 
uucico(8) daemon, and by the invoking user. 

Copy local source files to the spool directory. Thisisthe default. 

C reate all necessary directories when doing the copy. T his is the default. 

If any necessary directories do not exist for the destination path, abort thecopy. 

Set the grade of the fi le transfer command. J obs of a higher grade are executed fi rst. G rades 
run 0 ... 9 a ... z a ... z from high to low. 

Report completion or fai lure of thefi le transfer by maii(l). 

Report completion or failure of the file transfer by maii(l) to the named user on the remote 
system. 

Do not start uucico(8) daemon immediately; merely queue up the file transfer for later 
execution. 

Print j obi d on standard output. The job may be later canceled by passing thej obi d to the 

-k switch of uustat(l). It is possible for some complex operations to produce more than 

onej obi d, in which case, each will be printed on a separate line. For example, 

uucp sysl !"userl/fi I el sys2 !"user2/fi I e2 "user 3 

will generate two separatejobs, onefor the system sysi and one for the system s y s 2 . 

Do not prepend remote relative pathnames with the current directory. 

T urn on particular debugging types. The following types are recognized: abnormal, chat, 
handshake, uucp-proto, proto, port, config, spooldir, execute, incoming, outgoing. 

0 nly abnormal, config, spooldir, and execute are meaningful for uucp. M ulti pie types 
may be given, separated by commas, and the - - debug option may appear multiple times. A 
number may also be given, which will turn on that many types from the foregoing list; for 
example, - -debug 2 is equivalent to --debug abnormal, chat. 

Set configuration file to use. Thisoption may not be available depending upon how uucp 
was compiled. 

Report version information and exit. 

Print a help message and exit. 


FILES 

The filenames may be changed at compilation time or by the configuration file, so these are only approximations. 



uuencode 


/usr/lib/uucp/config 
/usr/spool/uucpuucp 
/usr/spool/uucp/Log 
/usr/spool/uucppublic 


Configuration file 
spool di rectory 
uucp logfile 

Default uucp public directory 


SEE ALSO 

mail(l), uux(l), uustat(l), uucico(8) 

BUGS 

Some of the options are dependent on the capabilities of theuucico(8) daemon on the remote system. 

The -n and -m switches do not work when transferring a file from one remote system to another. 

Filemodesarenot preserved, except for theexecute bit. T he resulting fi le is owned bytheuucp user. 

AUTHOR 

Ian LanceTaylor (ian@airs.com) 

Taylor UUCP 1.05 


uuencode 

uuencode— Encode a binary file 
uudecode- Decode a file created by uuencode 

SYNOPSIS 

uuencode [ -m] [file ] name 
uudecode [-0 outfile] [ file ]... 

DESCRIPTION 

uuencode and uudecode are used to transmit binary files over transmission mediums that do not support other than simple 
ASCII data. 

uuencode reads f i i e (or by default the standard input) and writes an encoded version to the standard output. The encoding 
uses only printing ASCI I characters and includes the mode of the file and the operand name for use by uudecode. If name is/ 
dev/stdout, the result will be written to standard output. By default, the standard uu encoding format will be used. If the 
option -m isgiven on thecommand line, base64 encoding isused instead. 

uudecode transforms uuencoded files (or by default, the standard input) into the original form. The resulting file is named 
name (or outfile if the -o option is given) and will have the mode of the original file except that setuid and execute bits 
are not retained. If outfile or name is /dev/stdout, the result will be written to standard output, uudecode ignores any 
leading and trailing lines. The program can automatically decide which of the supported encoding schemes are used. 

EXAMPLES 

The foil owing example packages up a source tree, compresses it, uuencodes it, and mails it to a user on another system. 
When uudecode is run on the target system, the file src_tr-ee.tar.z will be created, which may then be uncompressed and 
extracted into theoriginal tree. 

tar cf - src_tree | compress | uuencode src_tree.tar.Z j mail sysl!sys2!user 
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SEE ALSO 

compress(l), mail(l), uucp(l), uuencode(5) 

STANDARDS 

This implementation iscompliantwith P1003.2b/D 11. 

BUGS 

If more than one file is given to uudecode and the -o option is given or more than onename in the encoded files is the same, 
the result is probably not what is expected. 

The encoded form of the file is expanded by 37 percent for uu encoding and by 35 percent for base64 encoding (3 bytes 
become4 plus control information). 

HISTORY 

The uuencode command appeared in BSD 4.0. 


uustat 

uustat— uucp status inquiry and control 

SYNOPSIS 

uustat -a 
uustat --all 

uustat [ -eKRiMNQ ] [ - sS system ] [ -ull user ] [ -cC command ] [ -oy hours ] 

[ -B Ii nes ] [ --executions ][--kill-all ][--rejuvenate-all ][--prompt ][--mail ] 

[--notify ][--no-list ][--system system ] [ --not-system system ] [ --user user ] 

[--not-user user ] [ --command command ] [ --not-command command ] 

[ --older-than hours ] [ --younger-than hours ] [ --mail-lines lines ] 
uustat [ -kr jobid ] [ --kill jobid ] [ --rejuvenate jobid ] 

uustat -q [ -sS system ] [ -oy hours ] [ --system system ] [ --not-system system ] 

[--older-than hours ] [ --younger-than hours ] 

uustat --list [ -sS system ] [ -oy hours ] [ --system system ] 

[ --not-system system ] [ --older-than hours ] [ --younger-than hours ] 

uustat -m 

uustat --status 

uustat -p 

uustat --ps 

DESCRIPTION 

The uustat command can display various types of status information about theUUCP system. It can also be used to cancel 
or rejuvenate requests made by uucp(l) or uux(l). 

By default uustat displays all jobs queued up for the invoking user, as if given the - - user option with the appropriate 
argument. 



uustat 



If any Of the -a, --all, -e, --executions, -s, --system, -S,--not-system, -u, --user, -U, --not-user, -c, --command, -C, 
--not-command, -o, --oider-than, -y, --younger-than options are given, then all jobs that match the combined specifica¬ 
tions are displayed. 

The -k or - -kiii-aii option may be used to kill off a selected group of jobs, such as all jobs more than seven days old. 


OPTIONS 


The followi ng opti ons may be given to uustat. 


-a, - - all 

-e, --executions 


-s system, - -system system 


- S system, 

--not-system system 


-u user, --user user 

-U user , --not-user user 

-c c ommand, 

- - command c o mma nd 


-C c o mma nd, 

--not-command command 


-o hours, 

--older-than hours 
-y hours, 

--younger-than hours 


List all queued file transfer requests. 

List queued execution requests rather than queued filetransfer requests. Queued execution 
requests are processed by uuxqt(8) rather than uucico(8). Queued execution requests may 
be waiting for some file to be transferred from a remote system. They are created by an 
invocation of uux(l). 

List all jobs queued up for the named system. These options may be specified multiple 
times, in which case all jobs for all the systems will be listed. If used with -list, only the 
systems named will be listed. 

List all jobs queued for systems other than the one named. These options 
may be specified multi pletimes, in which case no jobs from any of the specified systems wi II 
be listed. If used with - - list, only the systems not named will be listed. These opti ons 
may not be used with -s or - -system. 

List all jobs queued up forthenamed user. These options may be specified multi pie times, 
in which case all jobs for all the users will be listed. 

List all jobs queued up for users other than the one named. These options may be specified 
multipletimes, in which case no jobs from any of the specified users will be listed. These 
options may not be used with -uor - -user. 

List all jobs requesting the execution of thenamed command. If command is all this will 
list all jobs requesting the execution of some command (as opposed to simply requesting a 
filetransfer). These options may be specified multipletimes, in which case all jobs 
requesting any of the commands will be listed. 

List all jobs requesting execution of some command other than thenamed 
command, or, if command isALL, list all jobsthat simply request a file transfer (as opposed 
to requesting the execution of somecommand).Theseoptions may be specified multiple 
times, in which case, no job requesting one of the specified commands will be listed. These 
options may not be used with -cor --command. 

List all queued jobs older than the given number of hours. If used with --list, only 
systems whose oldest job isolderthan thegiven number of hours will belisted. 

List all queued jobs younger than thegiven number of hours. If used with - - list, 
only systems whose oldest job is younger than thegiven number of hours will be 
listed. 


-k j obi d, - -kill j obi d 


-r j obi d, 

- -rejuvenate j o bi d 


Kill thenamed job. The job ID is shown by the default output format, as well as by the - j 
or -- jobid option to uucp(l) or uux(l). A job may only be killed by the user who created 
the job, or by theUUCP administrator or the superuser. The -k or - - kin options may be 
used multiple times on the command lineto kill several jobs. 

Rejuvenate the named job. Thiswill mark it as having been invoked atthecurrent 
time, affecting the output of the -o, - - older-than, -y, or - - younger-than options and 
preserving itfrom any automated cleanup daemon. T he job ID isshown by the default 
output format, as well as by the - j or - - jobid options to uucp(l) or uu(l). A job may only 
be rejuvenated by the user who created the job, or by the U U C P administrator or the 
superuser. The -r or - - rejuvenate options may be used multiple times on the command 
lineto rejuvenate several jobs. 
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-q, --list 


-m, - -status 
-P, --ps 
-i, - - prompt 

-K, - -kill-all 


-R, --rejuvenate-all 
-M, - - mail 


-N, - -notify 
-W, --comment 
-Q, - - no-list 
-x type, --debug t y pe 


-I file, --config file 


-v, - - version 
- -help 

EXAMPLES 


uustat -all 


uustat -executions 


D isplay the status of commands, executions and conversations for all remote systems for 
which commands or executions are queued. The-s, --system, -s, --not-system, -o, -- 
older-than, -y, and - - younger-than options may be used to restrict the systems that are 
listed. Systemsfor which no commands or executions are queued will never belisted. 

D isplay the status of conversations for all remote systems. 

D isplay the status of all processes holding uucp locks on systems or ports. 

For each listed job, prompt whether to kill the job or not. If the first character of the input 
lineisy ory, the job will be killed. 

Automatically kill each listed job. Thiscan be useful for automatic cleanup scripts, in 
conjunction with the - -man and - -notify options. 

Automatically rquvenateeach listed job. This may not be used with --kiii-aii. 

For each listed job, send mail totheUUCP administrator. If the job is ki lied (dueto -- 
kill-ail or - - prompt with an affirmative response), the mail will indicate that. A comment 
specified by the - -comment option may be included. If thejob is an execution, the initial 
portion of its standard input will be included in the mail message; the number of lines to 
include may beset with the - -mail-lines option (the default is 100 ). If the standard input 
containsnuii characters, itisassumed to be a binary file and is not included. 

For each listed job, send mail to the user who requested thejob. The mail is identical to that 
sent by the -m or - -mail options 

Specify a comment to be included in mail sent with the -m, - - mail, -n, or - - notify 
options. 

Do not actually list thejob, but only take any actions indicated by the - i, --prompt, -k, -- 
kill-all, -M, - -mail, -N, Or --notify options. 

T urn on particular debugging types. The following types are recognized: abnormal, chat, 
handshake, uucp-proto, proto, port, config, spooldir, execute, incoming, outgoing. 
Only abnormal, config, spooldir, and execute are meaningful for uustat. 

M ultiple types may be given, separated by commas, and the - - debug option may appear 
multipletimes. A number may also be given, which will turn on that many types from the 
foregoing list; for example, --debug 2 isequivalenttO --debug abnormal,chat. 

Set configuration file to use. This option may not be available depending upon how uustat 
was compiled. 

Report version information and exit. 

Print a help message and exit. 


D isplay status of all jobs. A sample output li ne is as follows: 

bugsA027h bugs ian 04-01 13:50 Executing rmail ian@airs.com (sending 1283 
bytes) 

The format is 

jobid system user queue-date command (size) 

Thejobid may be passed to the - -km or - - rejuvenate options. The size indicates how 
much dataisto be transferred to the remote system, and is absent for a file receive request. 
The--system, --not-system, --user, --not-user, --command, --not-command, --older- 
than, and - -younger-than optionsmay beused to control which jobs are listed. 

D isplay status of queued up execution requests. A sample output line is as follows: 

bugs bugslian 05-20 12:51 rmail ian 

The format is 

system requestor queue-date co mma n d 

The --system, - -not-system, --user, - -not-user, - -command, --not-command, --older- 
than, and - -younger-than optionsmay beused to control which requests are listed. 
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uustat -list D isplay status for all systems with queued-up commands. A sample output line is as follows: 

bugs 4C (1 hour) 0X (0 secs) 04-01 14:45 Dial failed 

This indicates the system, the number of queued commands, the age of the oldest queued 
command, the number of queued local executions, the age of the oldest queued execution, 
the date of the last conversation, and the status of that conversation. 

uustat -status D isplay conversation status for all remote systems. A sample output line is as follows: 

bugs 04-01 15:51 Conversation complete 

This indicates the system, the date of the last conversation, and the status of that conversa¬ 
tion. If the last conversation failed, uustat will indicate how many attempts have been 
made to call the system. If the retry period is currently preventing calls to that system, 
uustat also displaysthetimewhen thenextcall will be permitted. 

uustat -ps Display the status of all processes holding uucp locks. The output format issystem- 

dependent, as uustat simply invokes ps(l) on each process holding a lock. A sampleoutput 
line is as follows: 

uustat -command rmail -older-than 168 -kill-all -no-list -mail -notify - 
comment "Queued for over 1 week" 

Thiswill kill all rmaii commands that have been queued up waiting for delivery for over 
oneweek (168 hours). For each such command, mail will be sent both to theUUCP 
administrator and to the user who requested the rmaii execution. T he mail message sent 
will include the string given by the - -comment option. The - -no-iist option prevents any 
of the jobs from being listed on the terminal, so any output from the program will be error 
messages. 

FILES 

The filenames may be changed at compilation time or by the configuration file, so these are only approximations, 
/usr/iib/uucp/config Configuration file 
/usr/spooi/uucpuucp spool directory 

SEE ALSO 

ps(l), rmail(l), uucp(l), uux(l), uucico(8), uuxqt(8) 

AUTHOR 

Ian Lance Taylor (ian@airs. com) 

Taylor UUCP 1.05 


UUX 

uux— Remote command execution over uucp 

SYNOPSIS 

uux [ options ] command 

DESCRIPTION 

The uux command is used to execute a command on a remote system, or to execute a command on the local system using 
files from remote systems. The command is not executed immediately; the request is queued until theuucico(8) daemon 
calls the system and executes it. The daemon isstarted automatically unless one of the -r or --nouucico options is given. 
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The actual command execution isdonebytheuuxqt(8) daemon. 

Fileargumentscan be gathered from remote systems to theexecution system, as can standard input. Standard output may be 
directed to a file on a remote system. 

The command name may be preceded by a system name followed by an exclamation point if it is to be executed on a remote 
system. An empty system nameistaken as the local system. 

Each argument that contains an exclamation point istreated as naming a file The system thatthefileison is before the 
exclamation point, and the path name on that system follows it. An empty system nameistaken as the local system; this must 
be used to transfer a file to a command bei ng executed on a remote system. If the path is not absolute, it will be appended to 
the current working directory on the local system; the result may not be meaningful on the remote system. A pathname may 
begin with '/, in which case it is relative to theuucp public directory (usually /usr/ spool/uucppubiic) on the appropriate 
system. A pathname may begin with 'name/, in which case it is relative to the home directory of the named user on the 
appropriate system. 

Standard input and output may be redirected as usual; the pathnames used may contain exclamation points to indicate that 
they are on remote systems. N otethat the redirection characters must be quoted so that they are passed to uux rather than 
interpreted by the shell. Append redirection (») does notwork. 

All specified files are gathered together into a single directory before execution of the command begins This means that each 

file must have a distinct base name. For example, 

uux 'syslldiff sys2!"userl/foo sys3!'user2/foo >!foo.diff 1 

will fail because both files will be copied to sysi and stored under the name too. 

Arguments may be quoted by parentheses to avoid interpretation of exclamation points. This is useful when executing the 
uucp command on a remote system. 


OPTIONS 


T he followi ng options may be given to uux. 


-p, - -stdin 
-c, --nocopy 


-C, - -copy 
-1, - -link 


-g gr ade, --grade gr ade 

-n, --notification=no 
-z, --notification=error 


-r, - -nouucico 


Read standard input and use it as the standard input for the command to be executed. 

Do not copy local files to thespool directory. This is the default. If they are removed before 
being processed by theuucico(8) daemon, the copy will fail. The files must be readable by 
theuucico(8) daemon, as well as by the invoker of uux. 

Copy local files to thespool directory. 

Link local files into thespool directory. If a file can not be I inked because it is on a different 
device it will be copied unless one of the -c or - - nocopy options also appears (in other 
words, useof --link switches the default from --nocopy to --copy). If thefiles are changed 
before being processed by theuucico(8) daemon, the changed versions will be used. The 
files must be readable by the uucico(8) daemon, as well as by the invoker of uux. 

Set the grade of the fi le transfer command. J obs of a higher grade are executed fi rst. G rades 
run 0 ... 9 a ... z a ... z from high to low. 

Do not send mail about the status of the job, even if it fails. 

Send mail about the status of the job if an error occurs. For many uuxqt daemons, 
including the T aylor uucp uuxqt, this is the default action; for those, - - 
notif ication=e r r o r will haveno effect. H owever, some uuxqt daemons will send mail if 
thejob succeeds unless the - -notification=emor option isused, and someother uuxqt 
daemons will not send mail if the job fails unless the -- notif ication=emor option isused. 
Do not start theuucico(8) daemon immediately; merely queue up theexecution request for 
later processing. 



uux 


571 


- j, - -jobid 

-a address, 

- - requestor address 
-x type, - -debug type 


-I file, - -config file 

-v, - -version 
- - help 

EXAMPLES 

uux -z - sysi i rmaii useri— Execute the command rmaii useri on the system sysi, giving it as standard input 
whatever isgiven to uux as standard input. If a failure occurs, send a message using maii(l). 

uux 1 dif f -c sysi !'useri /filel sys 2 ! ”user 2 /file 2 >!file.diff' —Fetch thetwo named filesfrom system sysi and 
system sys 2 and execute ditt, putting the result in file, dif f in the current directory. The current directory must be 
writable by theuuxqt(8) daemon forthisto work. 

uux 'sysiiuucp 'useri/fiiei <sys 2 ! 'user 2 /f iie 2 > 1 —Execute uucp on the system sysi copying fiiei (on system 
sysi) to sys 2 . This illustrates the use of parentheses for quoting. 

RESTRICTIONS 

The remote system may not permit you to execute certain commands. M any remote systems only permit the execution of 
rmaii and rnews. 

Some of the options are dependent on the capabilities of theuuxqt(8) daemon on the remote system. 

FILES 

The filenames may be changed at compilation time or by the configuration file, so these are only approximations. 

/ usr/ lib /uucp/config C onfiguration file 

/usr/spooi/uucpuucp spool directory 

/usr/spool/uucp/Log uucp log file 

/usr/spooi/uucppubiic D efault uucp public directory 

SEE ALSO 

mail(l), uustat(l), uucp(l), uucico(8), uuxqt(8) 

BUGS 

Files can not dereferenced across multiple systems. 

T oo many jobids are output by - - jobid, and there is no good way to cancel a local execution requiring remote files. 

AUTHOR 

Ian LanceTaylor (ian@airs.com) 


Print jobids on standard output. A jobid will be generated for each file copy operation 
required to perform the operation. These file copies may be canceled by passing the jobid 
to the - -kill switch of uustat(l), which will make the execution impossibleto complete. 
Report job status to thespecified e-mail address. 

T urn on particular debugging types. The following types are recognized: abnormal, chat, 

handshake, uucp-proto, proto, port, config, spooldir, execute, incoming, outgoing. 

0 nly abnormal, config, spooldir, and execute are meaningful for uux. M ultipletypes 
may be given, separated by commas, and the - - debug option may appear multiple times. A 
number may also be given, which will turn on that many types from theforegoing list; for 
example, --debug 2 is equivalent to - -debug abnormal,chat. 

Set configuration file to use. This option may not be available depending upon how uux 
was compiled. 

Report version information and exit. 

Print a help message and exit. 
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uuxqt 

uuxqt— uucp execution daemon 

SYNOPSIS 

uuxqt [ opti ons ] 

DESCRIPTION 

The uuxqt daemon executes commands requested by uux(l) from either the local system or from remote systems. It is started 
automatically by theuucico(8) daemon (unless uucico(8) is given the -q or - -nouuxqt option). 

There is normally no need to run this command because it will be invoked by uucico(8). H owever, it can be used to provide 
greater control over the processing of the work queue. 

M ultiple invocations of uuxqt may be run at once, as controlled by themax-uuxqts configuration command. 

OPTIONS 

T he following options may be given to uuxqt: 

-c command, --command command 0 nly execute requests for the specified command. For example, 

uuxqt -command rmail 

-s system, --system system 0 nly execute requests originating from the specified system. 

-x type, --debug type Turn on particular debugging types. The following types are recognized: abnormal, 

chat, handshake, uucp-pnoto, proto, port, config, spooldir, execute, incoming, 
outgoing. 0 nly abnormal, config, spooldir and execute are meaningful for 
uuxqt. M ultiple types may be given, separated by commas, and the - - debug option 
may appear multi pie times. A number may also be given, which will turn on that 
many types from the foregoing list; for example, - -debug 2 is equivalent to --debug 
abnormal,chat. 

The debugging output is sent to the debugging file usually /usr/spool/uucp/ 

Debug, /usr/spool/uucp/DEBUG, Or /usr/spool/uucp/.Admin/audit.local. 

-i file, --config Set configuration file to use. This option may not be avai lable, dependi ng upon how 

uuxqt was compiled. 

-v, --version Report version information and exit. 

--help Print a help message and exit. 

FILES 

The filenames may be changed at compilation time or by the configuration file, so these are only approximations. 

/usr/iib/uucp/config Configuration file 

/usr/spooi/uucpuucp spool directory 

/usr/spool/uucp/Log uucp logflle 

/usr/spooi/uucppubiic D efault uucp public directory 

/usr/spooi/uucp/Debug D ebugging file 

SEE ALSO 

uucp(l), uux(l), uucico(8) 

AUTHOR 

Ian Lance Taylor (ian@airs. com) 
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w— Present who users are and what they are doing 

SYNOPSIS 

w [ -hin] [-user ] 

DESCRIPTION 

Thew utility prints a summary of the current activity on the system, including what each user is doing. The first line displays 
the current time of day, how long the system has been running, the number of users logged into the system, and the load 
averages. The load average numbers give the number of jobs in the run queue averaged over 1, 5, and 15 minutes. 

The fields output are the user's login name, the name of the terminal the user is on, the host from which the user is logged 
in, the time the user logged on, the time si nee the user last typed anything, and the name and arguments of the current 
process. 

The options are as follows: 

-h Suppress the heading 

-i 0 utput is sorted by idle time 

-n Show network addresses as numbers 

-w Interpret addresses and attempt to display them symbolically 

If a username is specified, the output is restricted to that user. 

FILES 

/var/run/utmp List of users on the system 

SEE ALSO 

who(l), finger(l), ps(l), uptime(l), 

BUGS 

The notion of the current process is muddy. The current algorithm is "the highest numbered process on the terminal that is 
not ignoring interrupts, or, if there is none, the highest numbered process on the terminal." Thisfai Is, for example, in critical 
sections of programs I ike the shell and editor, or when faulty programs running in the background fork and fail to ignore 
interrupts. (In cases where no process can be found, w prints a period.) 

TheCPU timeisonlyan estimate; in particular, if someone leaves a background process running afterlogging out, the 
person currently on that terminal is charged with the time 

Background processes are not shown, even though they account for much of the load on the system. 

Sometimes processes, typically those in the background, are printed with null or garbaged arguments In these cases, the 
nameof the command is printed in parentheses. 

Thew utility does not know about the new conventions for detection of background jobs. It will sometimes find a back¬ 
ground job instead of the right one. 

COMPATIBILITY 

The-f, -l, -s, and -w flags are no longer supported. 

HISTORY 

Thew command appeared in BSD 3.0. 


BSD 4, 6Junel993 
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wall 

wan— W rite a message to users 

SYNOPSIS 

wall [file] 

DESCRIPTION 

wail displays thecontentsoffileor, by default, its standard input, on the terminals of all currently logged in users. 

Only the superuser can write on the terminals of users who have chosen to deny messages or are using a program that 
automatically denies messages. 

SEE ALSO 

mesg(l), talk(l), write(l), shutdown(8) 

HISTORY 

A wail command appeared in AT&T v7. 

Linux 0.99, 8 M arch 1993 


wc 

wc— Print the number of bytes, words, and lines in files 

SYNOPSIS 

wc [-clw] [--bytes] [--chars] [--lines] [--words] [--help] [--version] [file...] 


DESCRIPTION 

This manual page documents the GN U version of wc. wc counts the number of bytes, whitespace-separated words, and 
newlines in each given file, or the standard input if none are given or when a file named - is given. It prints one line of 
counts for each file, and if the file was given as an argument, it prints the filename following the counts. If more than one 
filename isgiven, wc prints a final line containing the cumulative counts, with thefilenametotai. The counts are printed in 
the Order lines, words, bytes. 

By default, wc prints all three counts. Optionscan specify that only certain counts be printed. Optionsdo notundo others 
previously given, so wc - - bytes --words prints both the byte counts and the word counts 


OPTIONS 

-c, --bytes,--chars 
-w, - -words 
-1, - - lines 

- -help 

- - version 


Print only the byte counts. 

Print only theword counts. 

Print only the newline counts. 

Print a usage message and exit with a non-zero status. 
Print version information on standard output, then exit. 


GNU Text Utilities 
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whereis 

whereis— Locate the binary, source, and manual page files for a command 

SYNOPSIS 

whereis [ -bmsu ][-BMS directory... -f ] filename ... 

DESCRIPTION 

whereis locates source/binary and manualssections for specified files. T he suppl ied names are first stripped of leading 
pathname components and any (single) trailing extension of theform . ext, for example, .c. Prefixes of s. resulting from use 
of source code control are also dealt with, whereis then attempts to locate the desired program in a list of standard Linux 
places: 

/bin 

/usr/bin 

/etc 

/usr/etc 

/sbin 

/usr/sbin 

/usr/games 

/usr/games/bin 

/usr/emacs/etc 

/usr/lib/emacs/19.22/etc 

/usr/lib/emacs/19.23/etc 

/usr/lib/emacs/19.24/etc 

/usr/lib/emacs/19.25/etc 

/usr/lib/emacs/19.26/etc 

/usr/lib/emacs/19.27/etc 

/usr/lib/emacs/19.28/etc 

/usr/lib/emacs/19.29/etc 

/usr/lib/emacs/19.30/etc 

/usr/TeX/bin 

/usr/tex/bin 

/usr/interviews/bin/LINUX 

/usr/bin/X11 

/usr/X11/bin 

/usr/X11R5/bin 

/usr/X11 R6/bin 

/usr/X386/bin 

/usr/local/bin 

/usr/local/etc 

/usr/local/sbin 

/usr/local/games 

/usr/local/games/bin 

/usr/local/emacs/etc 

/usr/local/TeX/bin 

/usr/local/tex/bin 

/usr/local/bin/X11 

/usr/contrib 

/usr/hosts 

/usr/include 

/usr/g++-include 
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OPTIONS 

-b Search only for binaries. 

-m Search only for manual sections. 

-s Search only for sources. 

-u Search for unusual entries. A file is said to be unusual if it does not have one entry of each requested type. Thus 

whereisnn -mnn - unn* asks for those fi les in the current di rectory which haveno documentation. 

-b C hange or otherwise li mit the places where whereis searches for bi naries. 

-m Change or otherwise limit the places wherewhereis searches for manual sections. 

-s Change or otherwise limit the places where whereis searches for sources. 

-f T erminate the last directory list and signals the start of filenames; must be used when any of the -b, -m, or -s 

options are used. 

EXAMPLE 

Find all files in /usr/bin that are not documented in /usr/man/mani with source in /usr/src: 
example% cd /usr/bin 

example% whereis -u -M /usr/man/mani -S /usr/src -f * 

FILES 

/{bin,sbin,etc} 

/usr/{lib,bin,old,new,local,games,include,etc,src,man,sbin, 

X386, TeX, g++-include} 

/usr/local/{X386,TeX,XI1,include,lib,man,etc,bin,games,emacs} 

SEE ALSO 

chdir(2V) 

BUGS 

Since whereis uses chdir(2V) to run faster, pathnames given with the -m, -s, or -b must be full; that is, they must begin 
with a /. 

8 May 1994 

write 

write— Send a message to another user 

SYNOPSIS 

write user [ttyname ] 

DESCRIPTION 

write allows you to communicate with other users by copying lines from your terminal to theirs 
When you run thewrite command, the user you are writing to gets a message of the form: 

Message from yourname@yourhost on yourtty at hh:mm ... 

Any further lines you enter will be copied to the specified user's terminal. If the other user wants to reply, he or she must run 
write as well. 

When you are done, type an end-of-fileor interrupt character. The other user will see the message eof, indicating that the 
conversation is over. 
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You can prevent people (other than the superuser) from writing to you with themesg(l) command. Some commands, for 
example, nrott(l) and pr(l), may disallow writing automatically, so that your output isn't overwritten. 

If the user you want to write to is logged in on more than one terminal, you can specify which terminal to write to by 
specifying the terminal name as the second oper and to the write command. Alternatively, you can let write select one of 
the terminals— it will pick the one with the shortest idle time Thus, if the user is logged in at work and also dialed up from 
home the message will go to the right place. 

The traditional protocol for writing to someone is that the string -o, either at the end of a line or on a line by itself, means 
that it's the other person's turn to talk. The string oo means that the person believes the conversation to be over. 

SEE ALSO 

mesg(l), talk(l), who(l) 

HISTORY 

A write command appeared in Version 6 AT&T UNIX. 

12 March 1995 


xllperf 

xiipert— X11 server performance test program 

SYNTAX 

xllperf [ -option ... ] 

DESCRIPTION 

The xiipert program runs one or more performance tests and reports how fast an x server can execute the tests. 

M any graphics benchmarks assume that the graphics device is used to display the output of a single fancy graphics applica¬ 
tion, and that the user getshiswork done on someother device like a terminal. Such benchmarks usually measure drawing 
speed for lines, polygons, text, and so on. 

Because workstations are not used as standalone graphics engines, but as super-terminals, xiiperf measures window 
management performance aswell astraditional graphics performance xiiperf includes benchmarksforthetime it takes to 
create and map windows (as when you startup an application); to map a preexisting set of windows onto the screen (as when 
you deiconify an application or pop up a menu); and to rearrange windows (as when you slosh windows to and fro trying to 
find theoneyou want). 

xiiperf also measures graphics performance for operations not normally used in standalone graphics displays, but are 
nonetheless used frequently by x applications. Such operations include copypiane (used to map bitmaps into pixels), 
scrolling (used in text windows), and variousstipples and tiles (used for CAD and color halftoning, respectively). 

xiiperf should be used to analyze particular strengths and weaknesses of servers, and ismost useful to a server writer who 
wants to analyze and improve a server, xiiperf is meant to comprehensively exercise just about every X11 operation you can 
perform; itdoesnot purport to bea representative sampleof theoperationsthatXll applicationsactually use. Although it 
can beused asa benchmark, itwas written and isintended as a performance testing tool. 

As such, xiiperf does not whittle down measurements to a single Hexstones or Mexops number. We consider such numbers 
to be uninformative at best and misleading at worst. Some servers that are very fast for certain applications can be very slow 
for others. N o single number or small set of numbers is sufficient to characterize how an x implementation will perform on 
all applications. However, by knowledgeof your favorite application, you may be ableto use the numbers xiiperf reports to 
predict its performance on a given x implementation. 
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That said, you might also want to look at xiiperfcomp(l), a program to compare the outputs of different xiipert runs. You 
provide a list of files containing results from xiipert, and it lays them out in a nice tabular format. 

For repeatable results, xiipert should be run using a local connection on a freshly started server. The default configuration 
runs each test five times in order to see if each trial takes approximately the same amount of time. Strange glitches should be 
examined; if nonrepeatable, you might chalk them up to daemons and network traffic. Each trial is run for five seconds, in 
order to reduce random time differences. The number of objects processed per second isdisplayed to three significant digits, 
but you'll be lucky on most UN IX systems if the numbers are actually consistent to two digits xiipert moves the cursor out 
of the test window; you should be careful notto bump themouseand moveit back into the window. (A prize to peoplewho 
correctly explain why!) 

Before running a test, xiipert determines what the round trip time to the server is, and factors this out of the final timing 
reported. It ensures that the server has actually performed thework requested by fetching a pixel back from the test window, 
which means that servers talking to graphics accelerators can’t claim that they are done, while in the meantime the accelera¬ 
tor is painting madly. 

By default, xiipert automatically calibrates the number of repetitions of each test, so that each should take approximately 
thesamelength oftimeto run across servers of widely differing speeds. However, because each testmust be run to comple¬ 
tion at least once, some slow servers may take a very longtime, particularly on the window moving and resizing tests, and on 
the arc drawing tests. 

All timing reports are for the smallest object involved. For example, the line tests use a PoiyLine request to paint several lines 
at once, but report how many lines per second the server can paint, not how many PoiyLine requests per second. Text tests 
paint a line of characters, but report on thenumber of characters per second. Somewindow tests map, unmap, ormovea 
single parent window, but report on how many children windows per second the server can map, unmap, or move. 

The current program is mostly the responsibility of Joel M cCormack. It is based upon the xiipert developed by Phil 
Karlton, Susan Angebranndt, Chris Kent, M ary Walker, and T odd N ewman, who wanted to assess performance differences 
between various servers. Several tests were added in order to write and tune the PM AX (D EC Station 3100) servers. Fora 
general release to the world, xiipert was rewritten to ease making comparisons between widely varying machines, to cover 
most important (and unimportant) x functionality, and to exercise graphics operations in as many different orientations and 
alignments as possible 


OPTIONS 


xiipert is solely xiib based, and accepts the following options: 


-display host: dpy 

-sync 

-pack 


-repeat <n> 

-time <s> 

-all 
- range 

<t e s t 1 > [, <t e s 12 > ] 


-labels 

-fg col or-or-pi xel 
-bg coIor-or-pi xeI 
-clips def a u11 


Specifies which display to use. 

Runs the tests in synchronous mode. N ormally only useful fordebuggingxiipert. 

Runs rectangle tests so that they pack rectangles right next to each other. This makes it easy 
to debug server code for stipples and tiles; if the pattern looks ugly, you've got alignment 
problems. 

Repeats each test n times (by default each test is run fivetimes). 

Specifies how long in seconds each test should be run (defaults seconds). 

Runs all tests. This may takeawhile 

Runs all the tests starting from the specified namet est l until the name t est 2 , tests. The 
testnames should be one of the options starting from -dot. For example, -range uneioo 
will perform the tests from the 100 pixel line test, and go on till the last test; -range 
linel00,dlinel0 Will do thetestsfrom linel00 to dline10. 

Generates just the descriptive labels for each test specified. Seexiipertcomp for more 
details. 

Specifies the foreground color or pixel value to use. 

Specifies the background color or pixel value to use. 

D efault number of clip wi ndows. 
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-ddbg color-or-pixel 

-rop <rop0 ropl . . .> 

-pm <pmO pml . . .> 

-depth <dept h> 

-vclass <vcI a s s > 

-reps <n> 

-subs <s 0 si . . .> 


- v 1.2 


- v 1.3 
-su 


-bs 

<backing_store_hint> 

-dot 

-recti 

-rect10 

-rect100 

-rect500 

-srectl 

-srectl0 

-srectl00 

-srect500 

-osrectl 

-osrectIO 

-osrect100 

-osrect500 

-tilerectl 

-tilerect10 

-tilerect100 

-tilerect500 

-oddsrectl 

-oddsrect10 

-oddsrect100 

-oddsrect500 

-oddosrectl 

-oddosrect10 

-oddosrect100 

-oddosrect500 

-oddtilerectl 

-oddtilerect10 


Specifi es the color or pixel value to use for drawi ng the odd segments of a DoubieDashed 
lineor arc. Thiswill default to thebg color. 

Use specified raster ops (default is GXcopy). This option only affects graphics benchmarks in 
which the graphics function is actually used. 

U se specified planemasks (default is “ 0 ). This option only affects graphics benchmarks in 
which theplanemask is actually used. 

Useavisual with <depth> planes per pixel. (Default isthedefault visual.) 

U Se a visual with Of class <vcl ass>. <vcl ass> can be StaticGray, Grayscale, 

StaticColor, Pseudocolor, T rueColor, Or DirectColor. (D efault is the default visual). 
Specify the repetition count. (D efault is number that takes approximately five seconds.) 
Specify the number of sub windows to use in the Window tests. Default is 4 , 1 6, 25 , 50 , 75 , 
100 , and 200 . 

Perform only xiipert version 1.2 tests using version 1.2 semantics. 

Perform only xiipert version 1.3 tests using version 1.3 semantics. 

Set the save_under window attribute to True on all windows created by xiipert. Default is 
False. 

Set thebacking_store window attribute to the given value on all windows created by 
xl Iperf. <backing_store_hint> Can bewhenMapped Or Always. D efault iSNotUseful. 

Dot. 

lxl solid-filled rectangle. 

10x10 solid-filled rectangle. 

100x100 solid-filled rectangle. 

500x500 solid-filled rectangle. 

lxl transparent stippled rectangle, 8x8 stipple pattern. 

10x10 transparent stippled rectangle, 8x8 stipple pattern. 

100x100 transparent stippled rectangle, 8x8 stipple pattern. 

500x500 transparent stippled rectangle, 8x8 stipple pattern, 
lxl opaque stippled rectangle, 8x8 stipple pattern. 

10x10 opaque stippled rectangle, 8x8 stipple pattern. 

100x100 opaque stippled rectangle, 8x8 stipple pattern. 

500x500 opaque stippled rectangle, 8x8 stipple pattern, 
lxl tiled rectangle, 4x4 tile pattern. 

10x10 tiled rectangle, 4x4 tilepattern. 

100x100 tiled rectangle, 4x4 tilepattern. 

500x500 tiled rectangle, 4x4 tilepattern. 

lxl transparent stippled rectangle, 17x15 stipple pattern. 

10x10 transparent stippled rectangle, 17x15 stipple pattern. 

100x100 transparent stippled rectangle, 17x15 stipple pattern. 

500x500 transparent stippled rectangle, 17x15 stipple pattern, 
lxl opaque stippled rectangle, 17x15 stipple pattern. 

10x10 opaque stippled rectangle, 17x15 stipple pattern. 

100x100 opaque stippled rectangle, 17x15 stipple pattern. 

500x500 opaque stippled rectangle, 17x15 stipple pattern, 
lxl tiled rectangle, 17x15 tilepattern. 

10x10 tiled rectangle, 17x15 tilepattern. 
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-oddtilerect100 

-oddtilerect500 

-bigsrectl 

-bigsrect10 

-bigsrect100 

-bigsrect500 

-bigosrectl 

-bigosrect10 

-bigosrect100 

-bigosrect500 

-bigtilerectl 

-bigtilerect10 

-bigtilerect100 

-bigtilerect500 

-eschertilerectl 

-eschertilerectlO 

-eschertile recti 00 

-eschertilerect500 

-segl 

-seg10 

-seg100 

-seg500 

-seg100c1 

-seg100c2 

-seg10@c3 

-dseg10 

-dseg100 

-ddsegl00 

-bseg10 

-bseg100 

-bseg500 

-vseg10 

-vseg100 

-vseg500 

-whsegl0 

-whsegl00 

-whseg500 

-wvsegl0 

-wvsegl00 

-wvseg500 

-linel 

-line10 

-line100 

-line500 


100x100 tiled rectangle, 17x15 tilepattern. 

500x500 tiled rectangle, 17x15 tilepattern. 
lxl stippled rectangle, 161x145 stipple pattern. 

10x10 stippled rectangle, 161x145 stipple pattern. 

100x100 stippled rectangle, 161x145 stipple pattern. 
500x500 stippled rectangle, 161x145 stipple pattern, 
lxl opaque stippled rectangle, 161x145 stipple pattern. 
10x10 opaque stippled rectangle, 161x145 stipple pattern. 
100x100 opaque stippled rectangle, 161x145 stipple pattern. 
500x500 opaque stippled rectangle, 161x145 stipple pattern, 
lxl tiled rectangle, 161x145 tilepattern. 

10x10 tiled rectangle, 161x145 tilepattern. 

100x100 tiled rectangle, 161x145 tilepattern. 

500x500 tiled rectangle, 161x145 tilepattern. 
lxl tiled rectangle, 215x208 tilepattern. 

10x10 tiled rectangle, 215x208 tilepattern. 

100x100 tiled rectangle, 215x208 tilepattern. 

500x500 tiled rectangle, 215x208 tilepattern. 

1-pixel thin line segment. 

10-pixel thin linesegment. 

100-pixel thin linesegment. 

500-pixel thin linesegment. 

100-pixel thin linesegment (1 obscuring rectangle). 

100-pixel thin linesegment (2 obscuring rectangles). 
100-pixel thin linesegment (3 obscuring rectangles). 

10-pixel thin dashed segment (3 on, 2 off). 

100-pixel thin dashed segment (3 on, 2 off). 

100-pixel thin double-dashed segment (3 fg, 2 bg). 

10-pixel thin horizontal linesegment. 

100-pixel thin horizontal linesegment. 

500-pixel thin horizontal linesegment. 

10-pixel thin vertical linesegment. 

100-pixel thin vertical linesegment. 

500-pixel thin vertical linesegment. 

10-pixel wide horizontal linesegment. 

100-pixel wide horizontal linesegment. 

500-pixel wide horizontal linesegment. 

10-pixel wide vertical linesegment. 

100-pixel wide vertical linesegment. 

500-pixel wide vertical linesegment. 

1-pixel thin (width 0) line. 

10-pixel thin line. 

100-pixel thin line. 

500-pixel thin line. 
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-dlinel0 
-dlinel00 
-ddlinel00 
-wlinel0 
-wlinel 00 
-wline500 
-wdlinel00 
-wddline100 
-orect10 
-orectl00 
-orect500 
-worectl 0 
-worectl00 
-worect500 
-circlel 
-circlel0 
-circlel00 
-circle500 
-dcircle100 
-ddcirclel00 
-wcircle10 
-wcircle100 
-wcircle500 
-wdcirclel 00 
-wddcirclel00 
-pcircle10 
-pcircle100 
-wpcirclel0 
-wpcirclel 00 
-fcirclel 
- fcirclel0 
-fcircle100 
-fcircle500 
-fcpcirclel0 
-fcpcirclel00 
-fspcirclel0 

-fspcirclel00 

-ellipse10 

-ellipse100 

-ellipse500 

-dellipse100 

-ddellipsel00 

-wellipse10 


10-pixel thin dashed line(3 on, 2 off). 

100-pixel thin dashed Iine(3 on, 2 off). 

100-pixel thin double-dashed line(3 fg, 2 bg). 

10-pixel line, linewidth 1. 

100-pixel line, linewidth 10. 

500-pixel line, linewidth 50. 

100-pixel dashed line, linewidth 10 (30 on, 20 off). 

100-pixel double-dashed line, linewidth 10 (30 fg, 20 bg). 

10x10 thin rectangle outline. 

100-pixel thin vertical linesegment. 

500-pixel thin vertical linesegment. 

10x10 wide rectangle outline. 

100-pixel wide vertical linesegment. 

500-pixel wide vertical linesegment. 

1-pixel diameter thin (line-width 0 ) circle. 

10-pixel diameter thin circle. 

100-pixel diameter thin circle. 

500-pixel diameter thin circle. 

100-pixel diameter thin dashed circle (3 on, 2 off). 

100-pixel diameter thin double-dashed circle (3 fg, 2 bg). 

10-pixel diameter circle linewidth 1. 

100-pixel diameter circle, linewidth 10. 

500-pixel diameter circle, linewidth 50. 

100-pixel diameter dashed circle linewidth 10 (30 on, 20 off). 

100-pixel diameter double-dashed circle linewidth 10 (30 fg, 20 bg). 

10-pixel diameter thin partial circle, orientation and arc angle a/enly distributed. 

100-pixel diameter thin partial circle 
10-pixel diameter wide partial circle. 

100-pixel diameter wide partial circle. 

1-pixel diameter filled circle. 

10-pixel diameter filled circle 
100-pixel diameter filled circle. 

500-pixel diameter filled circle. 

10-pixel diameter partial-filied circle chord fill, orientation and arc angle evenly distributed. 
100-pixel diameter parti al-fi lied circle chord fill. 

10-pixel diameter parti al-fi lied circle pieslicefill, orientation and arc angleevenly 
distributed. 

100-pixel diameter parti al-fi lied circle, pieslicefill. 

10-pixel diameter thin (linewidth 0) ellipse, major and minor axis sizes evenly distributed. 
100-pixel diameter thin ellipse. 

500-pixel diameter thin ellipse. 

100-pixel diameter thin dashed ellipse (3 on, 2 off). 

100-pixel diameter thin doubledashed ellipse (3 fg, 2 bg). 

10-pixel diameter ellipse, linewidth 1. 
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-wellipsel 00 

-wellipse500 

-wdellipsel00 

-wddellipse100 

-pellipse10 

-pellipse100 

-wpellipse10 

-wpellipse100 

-fellipse10 

-fellipse100 

-fellipse500 

-fcpellipse10 

-fcpellipse100 

-fspellipse10 

-fspellipse100 

-trianglel 

-trianglel0 

- trianglel00 

-trapl 

-trap 10 

-trap100 

-trap300 

-strapl 

-strapl0 

-strapl00 

-strap300 

-ostrapl 

-ostrap10 

-ostrap100 

-ostrap300 

-tiletrapl 

-tiletrap10 

-tiletrap100 

-tiletrap300 

-oddstrapl 

-oddstrap10 

-oddstrap100 

-oddstrap300 

-oddostrapl 

-oddostrap10 

-oddostrap100 

-oddostrap300 

-oddtiletrapl 

-oddtiletrap10 


100-pixel diameter ellipse, line width 10. 

500-pixel diameter ellipse, line width 50. 

100-pixel diameter dashed ellipse, linewidth 10 (30 on, 20 off). 
100-pixel diameter double-dashed ellipse, linewidth 10 (30 tg, 20 pg). 
10-pixel diameter thin partial ellipse. 

100-pixel diameter thin partial ellipse. 

10-pixel diameter wide partial ellipse. 

100-pixel diameter wide partial ellipse. 

10-pixel diameter filled ellipse. 

100-pixel diameter filled ellipse. 

500-pixel diameter filled ellipse. 

10-pixel diameter partial-filied ellipse, chord fill. 

100-pixel diameter parti al-fi lied ellipse, chord fill. 

10-pixel diameter parti al-fi lied ellipse, pie slice fill. 

100-pixel diameter parti al-fi lied ellipse, pieslicefill. 

Fill 1-pixel/side triangle. 

Fill 10-pixel/side triangle. 

Fill 100-pixel/side triangle. 

Fill lxl trapezoid. 

Fill 10x10 trapezoid. 

Fill 100x100 trapezoid. 

Fill 300x300 trapezoid. 

Fill lxl transparent stippled trapezoid, 8x8 stipple pattern. 

Fill 10x10 transparent stippled trapezoid, 8x8 stipple pattern. 

Fill 100x100 transparent stippled trapezoid, 8x8 stipple pattern. 

Fill 300x300 transparent stippled trapezoid, 8x8 stipple pattern. 

Fill 10x10 opaque stippled trapezoid, 8x8 stipple pattern. 

Fill 10x10 opaque stippled trapezoid, 8x8 stipple pattern. 

Fill 100x100 opaque stippled trapezoid, 8x8 stipple pattern. 

Fill 300x300 opaque stippled trapezoid, 8x8 stipple pattern. 

Fill 10x10 tiled trapezoid, 4x4 tile pattern. 

Fill 10x10 tiled trapezoid, 4x4 tile pattern. 

Fill 100x100 tiled trapezoid, 4x4 tile pattern. 

Fill 300x300 tiled trapezoid, 4x4 tile pattern. 

Fill lxl transparent stippled trapezoid, 17x15 stipple pattern. 

Fill 10x10 transparent stippled trapezoid, 17x15 stipple pattern. 

Fill 100x100 transparent stippled trapezoid, 17x15 stipple pattern. 

Fill 300x300 transparent stippled trapezoid, 17x15 stipple pattern. 

Fill 10x10 opaque stippled trapezoid, 17x15 stipple pattern. 

Fill 10x10 opaque stippled trapezoid, 17x15 stipple pattern. 

Fill 100x100 opaque stippled trapezoid, 17x15 stipple pattern. 

Fill 300x300 opaque stippled trapezoid, 17x15 stipple pat-tern. 

Fill 10x10 tiled trapezoid, 17x15 tile pattern. 

Fill 10x10 tiled trapezoid, 17x15 tile pattern. 






-oddtiletrap100 

-oddtiletrap300 

-bigstrapl 

-bigstrap10 

-bigstrap100 

-bigstrap300 

-bigostrapl 

-bigostrap10 

-bigostrap100 

-bigostrap300 

-bigtiletrapl 

-bigtiletrap10 

-bigtiletrap100 

-bigtiletrap300 

-eschertiletrapl 

-eschertiletrapIO 

-eschertiletrapl00 

-eschertiletrap300 

-complex10 

-complex100 

-64poly10convex 

• 64poly100convex 

-64poly10complex 

-64poly100complex 

-ftext 

-f8text 

-f9text 

-f14text16 

■tr10text 

-tr24text 

-polytext 

-polytext16 

-fitext 

-f8itext 

-f9itext 

-f14itext16 

-f24itext16 

-trl 0itext 

-tr24itext 

-scroll10 

-scroll100 

- scroll500 


Fill 100x100 tiled trapezoid, 17x15 tile pattern. 

Fill 300x300 tiled trapezoid, 17x15 tile pattern. 

Fill lxl transparent stippled trapezoid, 161x145 stipple pattern. 

Fill 10x10 transparent stippled trapezoid, 161x145 stipple pattern. 
Fill 100x100 transparent stippled trapezoid, 161x145 stipple pattern 
Fill 300x300 transparent stippled trapezoid, 161x145 stipple pattern 
Fill 10x10 opaque stippled trapezoid, 161x145 stipple pattern. 

Fill 10x10 opaque stippled trapezoid, 161x145 stipple pattern. 

Fill 100x100 opaque stippled trapezoid, 161x145 stipple pattern. 

Fill 300x300 opaque stippled trapezoid, 161x145 stipple pattern. 

Fill 10x10 tiled trapezoid, 161x145 tile pattern. 

Fill 10x10 tiled trapezoid, 161x145 tile pattern. 

Fill 100x100 tiled trapezoid, 161x145 tile pattern. 

Fill 300x300 tiled trapezoid, 161x145 tile pattern. 

Fill lxl tiled trapezoid, 216x208 tile pattern. 

Fill 10x10 tiled trapezoid, 216x208 tile pattern. 

Fill 100x100 tiled trapezoid, 216x208 tile pattern. 

Fill 300x300 tiled trapezoid, 216x208 tile pattern. 

Fill 10-pixel/side complex polygon. 

Fill 100-pixel/side complex polygon. 

Fill 10x10 convex 64-gon. 

Fill 100x100 convex 64-gon. 

Fill 10x10 complex 64-gon. 

Fill 100x100 complex 64-gon. 

Character in 80-char line(6x13). 

Character in 70-char line(8x13). 

Character in 60-char line(9x15). 

2-byte character in 40-char line (kl4). 

Character in 80-char line(Times-Roman 10). 

Character in 30-char line(Times-Roman 24). 

Character in 20/40/20 line(6x13, Times-Roman 10, 6x13). 

2-byte character in 7/14/7 Iine(kl4, k24). 

Character in 80-char imageline(6xl3). 

Character in 70-char imageline(8xl3). 

Character in 60-char imageline(9xl5). 

2-byte character in 40-char image line (kl4). 

2-byte character in 23-char image line (k24). 

Character in 80-char image line (Times-Roman 10). 

Character in 30-char image line (Times-Roman 24). 

Scroll 10x10 pixels vertically. 

Scroll 100x100 pixels vertically. 

Scroll 500x500 pixels vertically. 
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copywinwin10 

Copy 10x10 square from window to window. 

copywinwin100 

C opy 100x100 square from window to window. 

copywinwin500 

C opy 500x500 square from window to window. 

copypixwin10 

C opy 10x10 square from pixmap to wi ndow. 

copypixwin100 

Copy 100x100 square from pixmap to window. 

copypixwin500 

Copy 500x500 square from pixmap to window. 

copywinpix10 

Copy 10x10 square from window to pixmap. 

copywinpix100 

C opy 100x100 square from window to pixmap. 

copywinpix500 

Copy 500x500 square from window to pixmap. 

copypixpix10 

C opy 10x10 square from pixmap to pixmap. 

copypixpix100 

Copy 100x100 square from pixmap to pixmap. 

copypixpix500 

Copy 500x500 square from pixmap to pixmap. 

copyplane10 

C opy 10x10 1-bit deep plane. 

copyplane100 

C opy 100x100 1-bit deep plane. 

copyplane500 

C opy 500x500 1-bit deep plane. 

putimage10 

Putlmage 10x10 square. 

putimage100 

Putl mage 100x100 square. 

putimage500 

Putlmage 500x500 square. 

putimagexy10 

PutlmageXY format 10x10 square. 

putimagexy100 

PutlmageXY format 100x100 square. 

putimagexy500 

PutlmageXY format 500x500 square. 

shmputIO 

Putlmage 10x10 square, M IT -shared memory extension. 

shmput100 

Putlmage 100x100 square, M IT-shared memory extension. 

shmput500 

Putlmage 500x500 square, M IT-shared memory extension. 

shmputxy10 

PutlmageXY format 10x10 square, M IT-shared memory extension. 

shmputxy100 

PutlmageXY format 100x100 square, M IT-shared memory extension 

shmputxy500 

PutlmageXY format 500x500 square, M IT-shared memory extension 

getimage10 

Getl mage 10x10 square. 

getimage100 

G etl mage 100x100 square. 

getimage500 

G etl mage 500x500 square. 

getimagexy10 

Getl mageXY format 10x10 square. 

getimagexy100 

Getl mageXY format 100x100 square. 

getimagexy500 

Getl mage XY format 500x500 square. 

noop 

X protocol NoOperation. 

atom 

GetAtomName. 

pointer 

QueryPointer. 

prop 

GetProperty. 

gc 

C hange graphics context. 

create 

Create child window and map using Mapsubwindows. 

ucreate 

C reate unmapped window. 

map 

M ap child window viaMapwindow on parent. 

unmap 

U nmap child window viaunmapwindow on parent. 

destroy 

D estroy child window via Destroywindow parent. 

popup 

H ide/expose window via M ap/U nmap pop-up window. 
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-move 

-umove 

-movetree 

- resize 

-uresize 

-circulate 

-ucirculate 


M ove window. 

M oved unmapped window. 

M ove window via Movewindow on parent. 
Resizewindow. 

Resize unmapped window. 

Circulate lowest window to top. 

Circulate unmapped window to top. 


X DEFAULTS 

T here are no x defaults used by this program. 


SEE ALSO 

X(l), xbench(l), xl 1 pertcomp(l) 


AUTHORS 

J oel M cC ormack 
Phil Karlton 
Susan Angebranndt 
Chris Kent 
Keith Packard 
G raeme Gill 


X Version 11 Release 6 
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xiiperfcomp— X11 server performance comparison program 

SYNTAX 

xllperfcomp [-rj -ro ] [ -1 label_file ] files 

DESCRIPTION 

The xiiperfcomp program merges the output of several xiiperf(l) runs into a nice tabular format. It takes the results in 
each file, fills in any missing test results if necessary, and for each test shows the objects second rate of each server. If invoked 
with the -r or - ro options, it shows the relative performance of each server to the first server. 

N ormally, xiiperfcomp uses the first file specified to determine which specific tests it should report on. Some(non-D EC:) 
servers may fail to perform all tests. In this case, xiiperfcomp automatically substitutes in a rate of 0.0 objects second. Since 
the first file determines which tests to report on, thisfile must contain a superset of the tests reported in the other files, else 
xl Iperfcomp Will fail. 

You can provide an explicit list of tests to report on by using the -1 switch to specify a file of labels. You can create a label file 
by using the -label option in xiiperf. 

OPTIONS 

xiiperfcomp accepts the following opti 0 ns: 

-r Specifies that the output should also include relative server performance. 

-ro Specifies that the output should includeonlyrelativeserverperformance 

-i_iabei_fiie Specifies a label file to use. 
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X DEFAULTS 

T here are no x defaults used by this program. 

SEE ALSO 

x(l), xllperf(l) 

AUTHORS 

M ark M oraes wrote the original scripts to compare servers. Joel M cCormackjust munged them together a bit. 

X Verson 11 Releas6 


xargs 

xargs— Build and execute command lines from standard input 

SYNOPSIS 

xargs [-0prtx] [-e[eof-str]] [-i[replace-str]] [-1[max - lines]] [-n max-args] 

[-s max-chars] [-P max-procs] [--null] [--eof[=eof-str]] [--replace[=replace-str]] 
[- - max-lines[=max-lines]] [--interactive] [--max-chars=max-chars] [--verbose] 
[--exit] [--max-procs=max-procs] [--max-args=max-args] [--no-run-if-empty] 
[--version] [--help] [command [initial-arguments]] 


DESCRIPTION 

This manual page documents the GN U version of xargs. xargs reads arguments from the standard input, delimited by 
blanks (which can be protected with double or single quotes or a backslash) or newlines, and executes the command (default is 
/bin/echo) oneor more ti mes with any initial-arguments followed by arguments read from standard input. Blank lines 
on the standard input are ignored. 

xargs exits with the following status: 

0 if it succeeds 

123 if any invocation of thecommand exited with status 1-125 

124 if thecommand exited with status 255 

125 ifthecommand is ki lied by a signal 

126 ifthecommand cannot be run 

127 ifthecommand is not found 
1 if some other error occurred. 


OPTIONS 

- -null, -0 


--eof[=eof-str], 
-e[eof-str] 


--help 

- - replace[=r e p I ace-str ], 
-i[r epl ace-str ] 


Input filenames are terminated by a null character instead of by whitespace, and the quotes 
and backslash are not special (every character istaken literally). D isablestheend-of-file 
string, which istreated like any other argument. Useful when arguments might contain 
whitespace, quote marks, or backslashes. The GN U find -printo option produces input 
suitable for this mode. 

Set the end-of-filestring to eof-str. If the end-of-filestring occurs as a line of input, the 
rest of the input isignored. If eof-str is omitted, there is no end of filestring. If this 
option is not given, the end-of-file string defaults to an underscore. 

Print a summary of theoptionsto xargs and exit. 

Replace occurrences of re pi ace-str intheinitial arguments with names read from 
standard input. Also, unquoted blanks do not terminate arguments. If replace-str 
is omitted, it defaults to {} (like for find -exec). Implies -x and -1 1. 
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- - max-lines[=max- lines], 
-l[max- I i nes] 

--max-args=max- a r gs, 

- n ma x - a r g s 

--interactive, -p 

--no - run-if-empty, -r 

--max-chars=max-chars, 

-s ma x-c ha r s 

- - verbose, -t 
--version 

--exit, -x 

--max-procs=max- procs, 

-P max-procs 


Use at most ma *-1 i nes nonblank inputlinesper command line; max -1 i nes defaults to i 
if omitted. T railing blanks cause an input lineto be logically continued on the next input 
line Implies -x. 

Use at most max - ar gs arguments per command line Fewer than max - args arguments will 
beused if the size (see the -s option) isexceeded, unless the -x option isgiven, in which 
Case xargs Will exit. 

Prompt the user about whether to run each command line and read a line from the 
terminal. Only run thecommand line if the response starts with y or y. Implies -t. 

If the standard input does not contain any nonblanks, do not run thecommand. N ormally, 
thecommand is run once even if there is no input. 

Use at most max-chars characters per command line including thecommand and initial 
arguments and the termi nati ng nulls at the ends of the argument strings. The default is 
as large as possible, up to 20k characters. 

Print thecommand line on the standard error output before executing it. 

Print the version number of xargs and exit. 

Exit if the size (see the -s option) isexceeded. 

Run up to max - procs processes at a time; the default is i. If max- pr oc s iso, xargs will 
run as many processes as possible at a time. Use the -n option with - p; otherwise, chances 
are that only oneexec will be done. 


SEE ALSO 

find(lL), iocate(lL), iocatedb( 5 L), updatedb(l) Finding Files (online in info, or printed) 


xauth 

xauth— x authority fileutility 

SYNOPSIS 

xauth [ -f authfile ][-vqib ][command arg ... ] 

DESCRIPTION 

The xauth program is used to edit and display the authorization information used in connecting to thex server. This 
program is usually used to extract authorization records from one machine and merge them in on another (as is the case 
when using remote logins or granting access to other users). Commands (described below) may be entered interactively, on 
the xauth command line, or in scripts. N ote that this program does not contact thex server. N ormally xauth is not used to 
create the authority file entry in the first place; xdm does that. 

OPTIONS 

The following options may beused with xauth. They may be given individually (for example, -q -i ) or may combined (for 
example, -qi). 

-f authfile This option specifies the name of the authority file to use. By default, xauth will use the file 

specified by thex authority environment variable or xauthority in theuser'shome 
directory. 

-q Thisoption indicates that xauth should operate quietly and not print unsolicited status 

messages. This isthe default if an xauth command isgiven on thecommand line or if the 
standard output isnot directed to aterminal. 

-v Thisoption indicates that xauth should operate verbosely and print status messages 

indicating the results of various operations (such as how many records have been read in or 
written out). This is the default if xauth is reading commands from its standard input and 
its standard output is directed to aterminal. 
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-i Thisoption indicates that xauth should ignore any authority fi le locks. Normally, xauth 

will refuse to read or edit any authority files that have been locked by other programs 
(usually xdm or another xauth). 

-b Thisoption indicates that xauth should attempt to break any authority file locks before 

proceeding. Use this option only to clean up stale locks. 

COMMANDS 

T he following commands may beused to manipulate authority files: 

add di spi ayname An authorization entry for the indicated display using the given protocol and key data is 

protocol name hexkey added to the authorization file. T he data is specified as an even-lengthed string of 

hexadecimal digits, each pair representing oneoctet. T hefirst digit of each pairgives 
the most significant 4 bits of the octet, and the second digit of the pair gives the least 
significant 4 bits For example, a 32-character hexkey would represent a 128-bit value. A 
protocol name consisting of just a single period is treated as an abbreviation for 

MIT-MAGIC-COOKIE -1. 

[njextract f i i ename Authorization entries for each of the specified displays are written to theindicated file. If 

di spi ayname ... the next ract command is used, the entries are written in a numeric format suitable for 

nonbinary transmission (such as secure electronic mail). The extracted entries can be read 
back in using the merge and nmerge commands. 

If the filename consists of just a single dash, the entries will be written to the standard 
output. 

[ n ] list [di spi ayname ... ] Authorization entries for each of the specified displays (or all if no displays are named) are 
printed on the standard output. If the mist command is used, entries will be shown in the 
numeric format used by thenextract command; otherwise, they are shown in a textual 
format. Key data is always displayed in the hexadecimal format given in the description of 
the add command. 

[n [merge [f i i e n a me ... ] Authorization entries are read from the specified files and are merged into the authorization 
database, superceding any matching existing entries. If the nmerge command is used, the 
numeric format given in the description oftheextract command is used. If a filename 
consists of just a single dash, the standard input will be read if it hasn't been read before, 
remove dispiayname... Authorization entries matching the specified displays are removed from the authority file 

source f i i ename The specified file is treated as a script containing xauth commands to execute. Blank lines 

and lines beginning with a pound sign (#) are ignored. A single hyphen may beused to 
indicate the standard input, if it hasn't already been read. 

into Information describing the authorization file, whether or not any changes have been made, 

and from where xauth commands are being read is printed on the standard output, 
exit If any modifications have been made, the authority file is written out (if allowed), and the 

program exits. An end-of-file is treated as an implicit exit command, 
quit Theprogram exits, ignoring any modifications This may also be accomplished by pressing 

the interrupt character. 

help [string] A description of all commands that begin with the given string (or all commands if no 

string is given) is printed on the standard output. 

? A short list of the valid commands is printed on thestandard output. 



DISPLAY NAMES 

Display names for the add, [njextract, [njiist, [n]merge,and remove commands use the same format as the display 
environment variableand thecommon -display command-lineargument. D isplay-specific information (such asthescreen 
number) is unnecessary and will be ignored. Same-machine connections (such as local-host sockets, shared memory, and the 
Internet Protocol hostname locaihost) are referred to ashostname/unix:dispiaynumber so that local entries for different 
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machines may be stored in one authority file. 

EXAMPLE 

The most common use for xauth is to extract the entry for the current display, copy it to another machine, and merge it into 
the user's authority file on the remote machine 
% xauth extract 

- $DISPLAY | rsh otherhost xauth merge - 

ENVIRONMENT 

This xauth program uses the following environment variables: 

xauth or i ty T o get the name of theauthority fileto useifthe -f option isn't used. 

home T o get the user's home directory if xauthority isn't defined. 

FILES 

$home/. xauthority is the default authority file if xauthority isn't defined. 

X Version 11 Release 6 




[n]list [di spl ayname ... 



] 


[n]merge [f i I ename... ] 


remove di spl ayname... 
source f i I ename 

info 

exit 

quit 

help [string] 


Authorization entries for each of the specified displaysfor all if 
no displays are named) are printed on thestandard output. If 
the mist command is used, entries will be shown in the 
numeric format used by the nextract command; otherwise, 
they are shown in a textual format. Key data is always 
displayed in the hexadecimal format given in the description of 
the add command. 

Authorization entries are read from the specified files and are 
merged into the authorization database, superseding any 
matching existing entries. If the merge command is used, the 
numeric format given in the description of the extract 
command isused. I f a filename consists of just a single dash, 
thestandard input will be read if it hasn't been read before. 
Authorization entries matching the specified displays are 
removed from the authority file. 

The specified fileistreated as a script containing xauth 
commandsto execute. Blank lines and lines beginning with at 
areignored. A singledash may beused to indicate the standard 
input, if it hasn't already been read. 

Information describing the authorization file, whether or not 
any changes have been made, and from where xauth com¬ 
mands are being read is printed on thestandard output. 

If any modifications have been made, the authority file is 
written out (if allowed), and the program exits. An end of file 
istreated as an implicit exit command. 

T he program exits, ignoring any modifications. T his may also 
be accomplished by pressing the interrupt character. 

A description of all commands that begin with thegiven string 
(or all commands if no string is given) isprinted on the 
standard output. 

A shortlist of thevalid commandsisprinted on thestandard 
output. 


DISPLAY NAMES 

Display names for the add, [njextract, [ n] list, [njmerge, and remove commands use the same format as the display 
environment variable and the common -display command-line argument. D i spl ay-specific information (such as the screen 
number) is unnecessary and will be ignored. Same-machine connections (such as local-host sockets, shared memory, and the 
Internet Protocol hostnamei ocai host ) are referred to ashostname/unixidispiaynumber so that local entries for different 
machines may be stored in one authority file. 


EXAMPLE 

The most common use for xauth isto extract the entry for the current display, copy it to another machine, and merge it into 
the user's authority file on the remote machine 


% xauth extract 

- $DISPLAY rsh otherhost xauth merge - 
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ENVIRONMENT 

T his xauth program uses the following environment variables: 

xauthoritv T o get the name of theauthority fileto use if the -f option 

isn't used 

home T o get the user's home directory if xauthority isn't defined 

FILES 

$home/. xauthority D efault authority fileif xauthority isn't defined 

BUGS 

Users that have unsecured networks should take care to use encrypted file transfer mechanisms to copy authorization entries 
between machines. Similarly, theMu-MAGic-cooKiE-i protocol isnot very useful in unsecured environments Sites that are 
interested in additional security may need to use encrypted authorization mechanisms such as Kerberos. 

Spaces are currently not allowed in the protocol name. Quoting could be added for the truly perverse. 

AUTHOR 

Jim Fulton, M IT X Consortium 

X Verson 11 Relea9s6 
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xbmtopbm— Convert an X11 orXIO bitmap into a portable bitmap 

SYNOPSIS 

xbmtopbm [bitmapfile] 

DESCRIPTION 

Readsan Xll orXIO bitmap as input. Produces a portable bitmap as output. 

SEE ALSO 

pbmtoxbm(l), pbmtox10bm(l), pbm(5) 

AUTHOR 

Copyright (c) 1988 byjef Poskanzer. 

31 August 1988 
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xcrasdb— Device Color Characterization utility for X Color M anagement System 

SYNOPSIS 

xcmsdb [ -query ][-remove ][-format 32j16j8 ][filename ] 
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DESCRIPTION 

xcmsdb is used to load, query, or remove device color characterization data stored in properties on the root window of the 
screen as specified in section 7, Device Color Characterization, of the ICC CM . Device color characterization data (also 
called the Device Profile) is an integral part of X lib's X Color M an agement System (xcms), necessary for proper conversion 
of color specification between device-independent and device-dependent forms, xcms uses 3x3 matrices stored in the 
xdccc_l i near_rgb_matr ices property to convert color specifications between CI EX YZ and RGB Intensity (XcmsRGBi, also 
referred to as linear RGB), xcms then uses display gamma information stored in the xdccc_linear_rgb_correction property to 
convert color specifications between RGBi and RGB device (XcmsRGB, also referred to as device RGB). 

N ote that xcms allows clients to register function sets in addition to its built-in function set for CRT color monitors. 
Additional function sets may store their device profile information in other properties in function set specific format. This 
utility is unaware of these nonstandard properties. 

The ASCI I readable contents of filename (or the standard input if no input file is given) are appropriately transformed for 
storage in properties, provided the -query or -remove optionsare not specified. 

OPTIONS 

xcmsdb program accepts thefollowing options: 

-query 

-remove 

-format 32j16j8 


SEE ALSO 

xprop(l), Xlib documentation 

ENVIRONMENT 

display T o figure out which display and screen to use 

AUTHOR 

C huck Adams, Tektronix, Inc., and Al Tabayoyon, SynChromatics, Inc. (added multivisual support) 

X Version 11 Release 6 


Thisoption attempts to readtheXDCCC properties off the 
screen's root window. If successful, it transforms the data into 
a more readable format, then sends the data to standard out. 
Thisoption attempts to remove theXDCCC properties on the 
screen's root window. 

Specifies the property format (32,16, or 8 bits per entry) for 
the xdccc_linear_rgb_correction property. Precision of 
encoded floating-point values increases with the increase in 
bits per entry. The default is 32 bits per entry. 
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xclock— Analog/digital clockforX 

SYNOPSIS 

xclock [ -help ][-analog ][-digital ][-chime ][-hd color ][-hi color ] 

[-update seconds ][-padding number ] 

DESCRIPTION 

The xclock program displays the time in analog or digital form. The time is continuously updated at a frequency which may 
be specified by the user. 
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OPTIONS 


xciock accepts all of the standard X Toolkitcommand-lineoptionsalongwith theadditional options listed here: 


-help 
-analog 
-digital Or-d 
-chime 

-hands col or (or-hd col or) 
-highlight col or (or -hi color) 

-update seconds 


-padding number 


This option indicates that a brief summary of the al lowed 
options should be printed on the standard error. 

Thisoption indicates that a conventional 12-hour clock face 
with tick marks and hands should be used. This is the default. 
Thisoption indicates that a 24-hour digital clock should be 
used. 

Thisoption indicates that the clock should chime once on the 
half hour and twice on the hour. 

Thisoption specifies the color of the hands on an analog 
clock. The default is black. 

Thisoption specifies the color of the edges of the hands on an 
analog clock, and isonly useful on color displays. The default 
is black. 

Thisoption specifies thefrequency in seconds at which xciock 
should update its display. If the clock is obscured and then 
exposed, it will be updated immediately. A value of 30 seconds 
or less will enable a second hand on an analog clock. The 
default is 60 seconds. 

Thisoption specifies the width in pixels of the padding 
between the window border and clock text or picture The 
default is 10 on a digital clock and 8 on an analog clock. 


X DEFAULTS 


This program uses the Clock widget. It understands all of the core resource names and classes as well as: 


width (class Width) 

height (class Height) 

update (class Interval) 
foreground (class Foreground) 

hands (class Foreground) 

highlight (class Foreground) 

analog (class Boolean) 
chime (class Boolean) 


Specifi es the wi dth of the clock. The default for analog clocks 
is 1 64 pixels; the default for digital clocks is whatever isneeded 
to hold the clock when displayed in the chosen font. 

Specifies the height of the clock. T he default for analog clocks 
is 1 64 pixels; the default for digital clocks is whatever isneeded 
to hold the clock when displayed in the chosen font. 

Specifies the frequency in seconds at which thetime should be 
redisplayed. 

Specifies the colorforthetick marks The default is depends 
On whether reverseVideo i SSpecif i ed. If reverseVideo is 
specified, thedefault isiwhite; otherwise, the default isbiack. 
Specifies the color of the insides of the clock's hands. T he 
default depends on whether reverseVideo is specified. If 
reverseVideo is specified, the default is lwhite; otherwise, the 
default is black. 

Specifi es the color used to hi ghl ight the clock's hands. T he 
default depends on whether reverseVideo isspecified. If 
reverseVideo is specified, the default is lwhite; otherwise; the 
default is black. 

Specifies whether or not an analog clock should be used 
instead of a digital one. T he default isTrue. 

Specifies whether or not a bell should be rung on the hour and 
half hour. 



xclipboard 



padding (class Margin) 


font (class Font) 


Specifies the amount of internal padding in pixels to beused. 
The default is 8. 

Specifies the font to beused forthedigital clock. N otethat 
variablewidth fonts currently will not always display correctly. 


WIDGETS 

In order to specify resources, it is useful to know the hierarchy of the widgets which compose xciock. In the following 
notation, indentation indicates hierarchical structure. The widget class name is given first, followed by the widget instance 
name 

XClock xciock 
Clock clock 

ENVIRONMENT 

display T o get the default host and display number 

xenvironment T o get the name of a resource file that overrides the global 

resources stored in the resourcej/ianager property 

FILES 

<xRoott/iib/xi i /app-defauits/xciock Specifies required resources 

SEE ALSO 

X(l), xrdb(l), time(3C) 

BUGS 

xciock believes the system clock. 

When in digital mode, the string should be centered automatically. 

AUTHORS 

Tony D ella Fera (MIT-Athena, D EC), Dave M ankins (M IT-Athena, BBN ), and Ed M oy (UC Berkeley) 

X Version 11 Release 6 


xclipboard 

xclipboard— X clipboard client 

SYNOPSIS 

xclipboard [ -toolkitoption ... ] [ -w ][-nw ] 

DESCRIPTION 

The xclipboard program is used to collect and display text selections that are sent to the Clipboard by other clients. It is 
typically used to save Clipboard selections for later use. It stores each Clipboard selection as a separate string, each of which 
can be selected. Each time Clipboard is asserted by another application, xclipboard transfers the contents of that selection to 
a new buffer and displays it in the text window. Buffers are never automatically deleted, so you'll want to use the delete 
button to get rid of useless items. 

Since xclipboard uses a T ext W idget to display the contents of the clipboard, text sent to the Clipboard may be reselected for 
use in other applications, xclipboard also responds to requests for the Clipboard selection from other clients by sending the 
entire contents of the currently displayed buffer. 
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An xciipboard window has the following buttons across the top: 


quit 

delete 

new 

save 

next 

previ ous 


When this button is pressed, xciipboard exits. 

When this button is pressed, the current buffer is deleted and 
the next one displayed. 

Creates a new buffer with no contents U seful in constructing 
a new Clipboard selection by hand. 

D isplaysa FileSavedialog box. Pressing the Accept button 
saves the currently displayed buffer to thefile specified in the 
text field. 

D isplays the next buffer in the list. 

D isplays the previous buffer. 


OPTIONS 

T he xciipboard program accepts all of thestandard X T oolkit command-line options as well as the following: 

-w Thisoption indicates that lines of text that are too longto be 

displayed on onelinein theclipboard should wrap around to 
the following lines. 

-nw Thisoption indicates that long lines of text should not wrap 

around. Thisisthedefault behavior. 


WIDGETS 

In order to specify resources, it is useful to know the hierarchy of the widgets which compose xciipboard. In the following 
notation, indentation indicates hierarchical structure. The widget class name is given first, followed by the widget instance 
name. 

xciipboard xciipboard 

Form form 

Command Quit 
Command delete 
Command new 
Command Save 
Command next 
Command prev 
Label index 
Text text 

TransientShell fileDialogShell 
Dialog fileDialog 
Label label 
Command accept 
Command cancel 
Text value 

TransientShell failDialogShell 
Dialog failDialog 
Label label 
Command continue 


SENDING/RETRIEVING CLIPBOARD CONTENTS 

T ext is copied to theClipboard whenever a client asserts ownership of theClipboard selection. T ext is copied from the 
Clipboard whenever a client requests the contents of theclipboard selection. Examples of event bindings that a user may 
wish to include in a resource configuration file to use the Clipboard are 


*VT100.Translations: #override \ 
<Btn3Up>: select-end(CLIPBOARD) \n\ 
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<Btn2Up>: insert-selection(PRIMARY,CLIPBOARD) \n\ 

<Btn2Down>: ignore () 

SEE ALSO 

x(l), xcutsei(l), xterm(l), individual client documentation for how to make a selection and send it to the Clipboard. 

ENVIRONMENT 

display T o get the default host and display number 

xenvironment T o get the name of a resource file that overrides the global 

resources stored in the resourcejvianager property 

FILES 

<xRoot>/iib/xi i /app-defauits/xciipboard Specifies required resources 

AUTHOR 

Ralph R. Swick (D EC/M IT Project Athena), ChrisD. Peterson (M IT X Consortium), Keith Packard (M IT X Consortium) 

X Version 11 Release 6 


xconsole 

xconsole— M onitor system console messages with X 

SYNOPSIS 

xconsole [ -tool ki t opt i on ...] [-file f i I e-name ] [-notify] [-stripNonprint] [-daemon] [-verbose] 
[-exitOnFail] 


DESCRIPTION 

The xconsole program displays messages that are usually sent to /dev/consoie. 


OPTIONS 


xconsole accepts all of the standard X T oolkit command-line options along with the additional options listed here 


-file f i I e - name 


-notify, -nonotify 


-daemon 


-verbose 


-exitOnFail 


To monitor someother device, usethisoption to specify the 
device name. T his does not work on regular files as they are 
always ready to be read from. 

W hen new data are received from the console and the notify 
option is set, the icon name of the application has* appended, 
so that it is evident even when the application isiconified. - 
notify is the default. 

This option causes xconsole to place itself in the background, 
using fork/exit. 

When set, thisoption directs xconsole to display an informa- 
tive message in thefirst line of thetext buffer. 

When set, thisoption directs xconsole to exit when it isunable 
to redirect the console output. 


X DEFAULTS 

This program uses the Athena Text widget, look in the Athena W idget Set documentation for controlling it. 
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WIDGETS 

In order to specify resources, it is useful to know the hierarchy of the widgets that compose xconsoie. In the following 
notation, indentation indicates hierarchical structure. The widget class name is given first, followed by the widget instance 
name. 

XConsole xconsoie 
XConsole text 

ENVIRONMENT 

display T o get the default host and display number. 

xenvironment T o get the name of a resource file that overrides the global 

resources stored in the resource_manager property. 

FILES 

<xRoot>/iib/xi i /app-defauits/xconsoie Specifies required resources 

SEE ALSO 

x(l), xrdb(l), Athena Text widget 

AUTHOR 

Keith Packard (M IT X Consortium) 

X Version 11 Release 6 


xcutsel 

xcutsei— Interchange between cut buffer and selection 

SYNOPSIS 

xcutsel [ -tool ki t option ...] [-selection sel ecti on ] [-cutbuffer number ] 

DESCRIPTION 

The xcutsel program is used to copy the current selection into a cut buffer and to make a selection that contains the current 
contents of the cut buffer. It acts as a bridge between applications that don't support selections and those that do. 

By default, xcutsel will use the selection named primary and the cut buffer cutbufferg. Either or both of these can be 
overridden by command-line arguments or by resources. 

An xcutsei window hasthefollowing buttons: 

quit When this button ispressed, xcutsei exits. Any selections held 

by xcutsei are automatically released. 

copy primary to 0 When this button ispressed, xcutsei copies the current 

selection into the cut buffer. 

copy 0 to primary When this button ispressed, xcutsei converts the current 

contents of the cut buffer into the selection. 

T he button labels reflect the selection and cut buffer selected by command-line options or through the resource database. 

When the copy 0 to PRIM ARY button is activated, the button will remain inverted as long as xcutsei remains the owner of 
theselection. Thisservesto remind you which client owns thecurrent selection. N ote that thevalueof the selection remains 
constant; if the cut buffer is changed, you must again activate the copy button to retrieve the new value when desired. 
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OPTIONS 

xcutsei accepts all of the standard X Toolkit command-line options as well as the following: 

-selection name This option specifies the name of the selection to use. T he 

default is primary. T he only supported abbreviations for this 
option are -select, -sei, and -s, asthe standard toolkit option 
-seiectionTimeout has a simi lar name. 

-cutbuffer number This option specifies the cut buffer to use. T he default is 

cutbuffer 0. 

X DEFAULTS 

Thisprogram accepts all of the standard X T oolkit resource names and classes as well as the following: 

selection (class selection) This resource specifies the name of the selection to use. T he 

default is primary. 

cutBufter (class cutBuffer) T his resource specifies the number of the cutbuffer to use. 

The default is 0 . 


WIDGET NAMES 

The following instance names may be used when user configuration of the labels in them is desired: 
sel-cut (class Command) T his is the "Copy SELECTION tO BUFFER" button, 

cut-sel (class Command) T his is the "Copy BUFFER tO SELECTION" button, 

quit (class Command) T his is the “guit" button. 

SEE ALSO 

x(l), xciipboard(l), xterm(l), text widget documentation, individual client documentation for how to make a selection. 

BUGS 

T here is no way to change the name of the selection or the number of the cut buffer while the program is running. 

AUTHOR 

Ralph R. Swick (D EC/M IT Project Athena) 

X Version 11 Rdee9s6 


xdm 

xdm— X D isplay M anagerwith support for XD M CP, host chooser 

SYNOPSIS 

xdm [ -config confi gurationfiI e ][-nodaemon ][-debug debugl evel ] 

[-error error! ogfiI e ][-resources resourcefiI e ][-server serverent ry ] 

[-sessi onsessi on program] 

DESCRIPTION 

xdm manages a collection of X displays, which may be on the local host or remote servers. The design of xdm was guided by 
the needs of X terminals as well as the X Consortium standard xdmcp, theX D isplay M anager C ontrol Protocol, xdm provides 
services si mi lar to those provided by imt, getty, and login on character terminals: prompting for login name and password, 
authenticating the user, and running a session. 
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A session is defined by the lifetime of a particular process; in the traditional character-based terminal world, it is the user's 
login shell. In the xdm context, it is an arbitrary session manager. This is because in a windowing environment, a user's login 
shell process does not necessarily have any terminal-like interface with which to connect. When a real session manager is not 
available, a window manager or terminal emulator is typically used as the session manager, meaning that termination of this 
process terminates the user's session. 

When thesession is terminated, xdm resets theX server and (optionally) restarts the whole process. 

When xdm receives an Indirect query via XD M CP, it can run a chooser process to perform an XD M CP B roadcastQ uery (or 
an XD M CP Query to specified hosts) on behalf of the display and offer a menu of possible hosts that offer XDM CP display 
management. This feature is useful with X terminals that do not offer a host menu themselves. 

Because xdm provides the first interface that users will see, it is designed to be simple to use and easy to customize to the needs 
of a particular site, xdm has many options most of which have reasonable defaults. Browse through the various sections of this 
manual, picking and choosing the things you want to change. Pay particular attention to the "Session Program" subsection, 
which will describe how to set up the style of session desired. 

OVERVIEW 

xdm is highly configurable, and most of its behavior can be controlled by resource files and shell scripts. The names of these 
files themselves are resources read from the filexdm-config or the file named bythe-config option. 

xdm offers display management two different ways. It can manage X servers running on the local machine and specified in 
xservers, and it can manage remote X servers (typically X terminals) using xdmcp (theXD M Control Protocol) as specified in 
the Xaccess file. 

The resources of theX clients run by xdm outside the user's session, including xdm's own login window, can be affected by 
setting resources in thexresources file. 

ForX terminals that do not offer a menu of hosts to get display management from, xdm can collect willing hosts and run the 
chooser program to offer the user a menu. ForX displays attached to a host, this step is typically not used, as the local host 
does the display management. 

After resetting theX server, xdm runs the xsetup script to assist in setting up the screen the user sees along with thexiogin 
widget. 

When the user logs in, xdm runs the xstartup script as root. 

Then xdm runs the xsession script as the user. This system session file may do some additional startup and typically runs a 
script in the user's home directory. When the xsession script exits, thesession is over. 

At the end of thesession, thexreset script is run to clean up, theX server is reset, and the cycle starts over. 

The file /usr/xiiR6/iib/xn/xdm/xdm-errors will contain error messages from xdm and anything output to stdem by xsetup, 
xstartup, xsession, or xreset. When you have trouble getting xdm working, check this file to see if xdm has any clues to the 
trouble. 

OPTIONS 

All of these options, except -contig itself, specify values that can also be specified in the configuration file as resources. 

-contig confi gurati on_fi i e N am es the configuration file, which specifies resources to 

Control the behavior Of xdm. <XRoot>/lib/X11/xdm/xdm-config is 
the default. See the subsection called "Configuration File.” 

-nodaemon Specifies false as the value for the DisplayManager .daemonMode 

resource. This suppresses the normal daemon behavior, which 
is for xdm to close all file descriptors, disassociate itself from the 
controlling terminal, and put itself in the background when it 
first starts up. 
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-debug debug_l evel 


-error errorl ogfiI e 


-resources resource file 


-server serverentry 


-udpPort port_number 


-session sessi onprogram 


-xrm resourcespeci fi cati on 


Specifies the numeric value for theDisplayManager.debugLevel 
resource. A non-zero value causes xdm to print lots of 
debugging statementsto the terminal; it also disables the 

DisplayManager.daemonModeresource, forcing xdm to run 
synchronously. T o interpret these debugging messages, a copy 
of the source code for xdm is almost a necessity. N o attempt has 
been made to rationalize or standardize the output. 

Specifies the value for theDisplayManager. errorLogFile 
resource. Thisfilecontainserrors from xdm as well as anything 
written to stderr by the various scripts and programs run 
during the progress of the session. 

Specifies the value for the DispiayManager* resources resource. 
This file is loaded using xrdb to specify configuration 
parametersfor the authentication widget. 

Specifies the value for the DispiayManager. servers resource. 

See the subsection "Local Server Specification” for a descrip¬ 
tion of this resource 

Specifies the value for the DispiayManager. request Port 
resource. This sets the port number, which xdm will monitor 
forXDM CP requests. AsXD M CP uses the registered well- 
known UD P port 177, this resource should not be changed 
except for debugging. 

Specifies the value for theDispiayManager*session resource. 
This indicates the program to run as the session after the user 
has logged in. 

Allows an arbitrary resource to be specified, as in mostX 
T oolkit applications 


RESOURCES 

At many stages the actions of xdm can be controlled through the use of its configuration file, which is in theX resource 
format. Some resources modify the behavior of xdm on all displays, while others modify its behavior on a single display. 

Where actions relate to a specific display, the display name is inserted into the resource name between Display-Manager and 
the final resource name segment. 

For local displays, the resource name and class areas read from thexservers file. 

For remote displays, the resource name is what the network address of the display resolves to. SeetheremoveDomain resource. 
The name must match exactly; xdm is not aware of all the network aliases that might reach a given display. If the name resolve 
fails the address is used. The resource cl ass is as sent by the display in theXDM CP M anage request. 

Because the resource manager uses colons to separate the name of the resource from its value and dots to separate resource 
nameparts xdm substitutes underscores for both dots and colons when generating the resource name. For example, 
DispiayManager .expo x org 0 . startup is the name of the resource that defi nes the startup shell file for the expo, x.org ■.% 
display. 

DispiayManager. servers This resource either specifies a filename full of server entries, 

one per line (if the value starts with a slash), or a single server 
entry. See the subsection "Local Server Specification" for the 
details. 

T his indicates the U D P port number that xdm uses to listen for 
incomingXD M CP requests. U nlessyou need to debug the 
system, leave thiswith its default value of 177 . 


DispiayManager.requestPort 
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DisplayManager.errorLogFile 


DisplayManager.debugLevel 


DisplayManager.daemonMode 


DisplayManager.pidFile 


DisplayManager.lockPidFile 


DisplayManager.authDir 


DisplayManager.autoRescan 


DisplayManager.removeDomainname 


DisplayManager.keyFile 


Error output is normally directed at the system console. T o 
redirect it, set this resource to afilename. A method to send 
these messages to sysiog should be developed for systems that 
support it; however, thewide variety of interfaces precludes 
any system-independent implementation. Thisfilealso 
contains any output directed to stderr by thexsetup, xstartup, 
xsession, and xreset files, so it will contain descriptions of 
problemsin those scripts as well. 

If the i nteger value of this resource is greater than zero, reams 
of debugging information will be printed. It also disables 
daemon mode, which would redirect the information into the 
bit-bucket, and allows nonroot users to run xdm, which would 
normally not be useful. 

N ormally, xdm attempts to make itself into a daemon process 
unassociated with any terminal. This is accomplished by 
forking and leaving the parent process to exit, then closing file 
descriptors and releasing the controlling terminal. In some 
environments this is not desired (in particular, when 
debugging). Setting this resource to false will disablethis 
feature. 

The filename specified will be created to contain an ASCII 
representation of the process-id of the main xdm process, xdm 
also uses file locking on thisfileto attempt to eliminate 
multiple daemons running on the same machine, which would 
cause quite a bit of havoc. 

This is the resource which controls whether xdm uses file 
locking to keep multiple display managers from running 
amok. On System V, thisusestheiockf library call, while on 
BSD itusesfiock. 

This names a directory in which xdm stores authorization files 
while initializing the session. T he default value isy. 
ThisBoolean controls whether xdm rescans the configuration, 
servers, access control and authentication keys files after a 
session terminates and the files have changed. By default it is 
true. You can force xdm to reread these files by sending a 
sighup to the main process. 

When computing the display nameforxDMCP clients, the name 
resolver will typically create a fully qualified hostname for the 
terminal. As this is sometimes confusing, xdm will remove the 
domain name portion of the hostname if itisthesameas the 
domain name of the local host when this variable is set. By 
default the value istrue. 

xdm-authentication -i styleXDM CP authentication requires 
that a private key be shared between xdm and the terminal. This 
resource specifies the file containing those values. Each entry 
in thefile consists of a display name and the shared key. By 
default, xdm does not include support for xdm-authentication-i, 
as it requires des, which isnot generally distributable because 
of U nited States export restrictions. 
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DisplayManager.accessFile 


DisplayManager.exportList 


DisplayManager.randomFile 


DisplayManager.greeterLib 


DisplayManager.choiceTimeout 


DisplayManager.Dl SPLAY .resources 


DisplayManager.Dl SPLAY .chooser 

DisplayManager.Dl SPLAY .xrdb 
DisplayManager.Dl SPLAY .cpp 
DisplayManager.Dl SPLAY .setup 


DisplayManager.Dl SPLAY .startup 


DisplayManager.Dl SPLAY .session 


T o prevent unauthorized XD M CP service and to allow 
forwarding of XDM CP indirectQuery requests, this file 
contains a database of hostnames that are either allowed direct 
access to thismachine or havea list of hosts to which queries 
should be forwarded to. The format of this file is described in 
the subsection "XD M CP Access Control." 

A list of additional environment variables, separated by 
whitespace, to pass on to the xsetup, xstartup, xsession,and 
xreset programs. 

A fileto checksum to generate the seed of authorization keys. 
This should be a file that changes frequently. T he default is 
/dev/mem. 

On systemsthat support a dynamically loadable greeter library, 
the name of the library. Default is <XRoot>/iib/xi i /xdm/ 
libXdmGreet.so. 

N umber of seconds to wait for display to respond after user 
has selected a host from the chooser. If the display sends an 
XD M CP indirectQuery within thistime the request is 
forwarded to thechosen host. Otherwise, it isassumed to be 
from a new session and the chooser is offered again. Default 
is 1 5. 

This resource specifies the nameof thefile to be loaded by 
xrdb as the resource database onto the root window of screen 0 
of the display. The xsetup program, the Login widget, and 
chooser will use the resources set in this file. T his resource 
database is loaded just before the authentication procedure is 
started, so it can control the appearance of the login window. 
See the subsection "Authentication Widget," which describes 
the vari ous resources that are appropri ate to pi ace i n th is fi le 
T here is no default value for this resource, but <xRoot>/iib/ 
xii/xdm/xresources istheconventional name. 

Specifies the program run to offer a host menu for indirect 
queries redirected to thespecial hostname chooser. <xRoot> 

/ lib/xi i/xdm/chooser is the default. See the subsections 
"XD M CP Access Control" and "chooser.” 

Specifies the program used to load the resources. By default, 
xdm uses <XRoot>/bin/xrdb. 

T his specifies the name of the C preprocessor that isused by 
xrdb. 

T his specifies a program that is run (as root) before offering 
the Login window. This may be used to change the appearance 
of the screen around the Login window or to put up other 
windows (for example you may want to run xconsoie here). 
Bydefault, no program is run. The conventional name fora 
fileused hereisxsetup. See the subsection "Setup Program." 
This specifies a program that is run (as root) after the 
authentication process succeeds. By default, no program is run. 
The conventional name for a file used hereisxstartup. Seethe 
subsection "Startup Program." 

This specifies the session to be executed (not running as root). 
By default, <xRoot>/bin/xte™ is run. The conventional name 
is xsession. See the subsection "Session Program." 
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DisplayManager.DI SPLAY.reset 


DisplayManager.DI SPLAY .openDelay, 
DisplayManager.DI SPLAY .openRepeat, 
DisplayManager.DI SPLAY .openTimeout, 
DisplayManager.DI SPLAY .startAttempts 


DisplayManager.DI SPLAY .pinglnterval, 
DisplayManager.DI SPLAY. pingTimeout 


DisplayManager.DI SPLAY. 
terminateServer 


DisplayManager.DI SPLAY.userPath 


DisplayManager.DI SPLAY. 
systemPath 


This specifies a program which is run (as root) after the session 
terminates. Again, by default, no program is run. The 
conventional nameisxreset. Seethesubsection "Reset 
Program.” 

T hese numeric resources control the behavior of xdm when 
attempting to open intransigent servers. openDelay isthe length 
of the pause (in seconds) between successive attempts, 
openRepeat isthe number Of attempts to make, openTimeout is 
the amount of time to wait while actually attempting the open 
(that is, the maximum time spent in theconnect(2) system 
call) and startAttempts isthe number of times this entire 
process is done before giving up on the server. After openRepeat 
attempts have been made, or if openTimeout seconds elapse in 
any particular attempt, xdm terminates and restarts the server, 
attempting to connect again. T his process is repeated 
startAttempts times, at which point the display is declared 
dead and disabled. Although this behavior may seem arbitrary, 
it has been empirically developed and works quite well on 
most systems. The default values are 5 for openDelay, 5 for 
openRepeat, 30 for openTimeout and 4 for startAttempts. 

T o discover when remote displays disappear, xdm 
occasionally pings them, using an X connection and xsync 
calls, pinglnterval specifies the time (in minutes) between 
each ping attempt, pingTimeout specifies the maximum 
amount of time (in minutes) to wait for the terminal to 
respond to the request. If the terminal does not respond, the 
session is declared dead and terminated. By default, both are 
set to 5 minutes. If you frequently useX terminalsthat can 
become isolated from the managing host, you might want to 
increase this value. The only worry is that sessions will 
continue to exist after the terminal has been accidentally 
disabled, xdm will not ping local displays. Although it would 
seem harmless, it is unpleasant when the workstation session is 
terminated as a result of the server hanging for N FS service 
and not responding to the ping. 

This Boolean resource specifies whether the X server should be 
terminated when asession terminates (instead of resetting it). 
This option can be used when the server tends to grow 
without bound overtime, in order to limit the amount of time 
the server is run. The default value istaise. 
xdm setsthePATH environment variablefor the session to this 
value. It should be a colon separated list of directories; see 
sh(l) forafull description. :/bin:/usr/bin:/usr/X11R6/bin 
: /usr/ucb is a common setting. The default value can be 
specified at build timein thex system configuration file with 
DefaultUserPath. 

xdm setsthePATH environment variablefor the startup and reset 
scripts to the value of this resource T he default for this 
resource isspecified at build time by the Detauitsystem-Path 
entry in the system configuration file; /etc:/bin:/usr/bin 
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DisplayManager.DI SPLAY. 
systemShell 

DisplayManager.DI SPLAY 
failsafeClient 


DisplayManager.DI SPLAY .grabServer, 
DisplayManager.DI SPLAY. grabTimeout xdm 


DisplayManager.DI SPLAY .authorize, 
DisplayManager.DI SPLAY.authName 


DisplayManager.DI SPLAY.authFile 


DisplayManager.DI SPLAY. 
authComplain 

DisplayManager.DI SPLAY. 
resetSignal 

DisplayManager.DI SPLAY. 
termSignal 


: /usr/xi iR6/bin: / usr/ ucb isacommon choice. Note the 
absence off.) from this entry. This is a good practice to follow 
for root; it avoids many common T rojan H orse system 
penetration schemes. 

xdm setsthesHEn environment variable for thestartup and 
reset scripts to the value of this resource. Itis/bin/sh by 
default. 

If the default session failsto execute, xdm will fall back to this 
program. This program is executed with no arguments, but 
executes usi ng the same environment variables as the session 
would have had. (See the subsection "Session Program.'') By 
default, <xRoot>/bin/xterm isused. 

T o improve security, this grabs the server and keyboard while 
reading thelogin nameand password. The grabServer resource 
specifies if the server should beheld for theduration of the 
nam^password reading. When false, theserver isungrabbed 
after the keyboard grab succeeds; otherwise, the server is 
grabbed until just before the session begins. The default is 
false. The grabTimeout resource specifies the maxi mum time 
xdm will wait for the grab to succeed. T he grab may fail if some 
other client has theserver grabbed, or possibly if thenetwork 
latencies are very high. T his resource has a default value of 3 
seconds; you should be cautious when raising it, as a user can 
be spoofed by a look-alike window on the display. If the grab 
fails, xdm killsand restarts the server (if possible) and the 
session. 

authdrize is a Boolean resource that controls whether xdm 
generates and uses authorization for the local server connec¬ 
tions. If authorization isused, authName is a list of authorization 
mechanisms to use, separated by whitespace. XD M C P 
connections dynamically specify which authorization 
mechanisms are supported, so authName isignored in thiscase. 
When authorize is set for a display and authorization is not 
available, theuser isinformed by having a different message 
displayed in theLogin widget. By default, authorize is true. 

authName iSMIT-MAGIC-COOKIE-1, Or, if XDM-AUTHORIZATION -1 is 

available, xdm-authorization-i mit-magic-cookie-i . 
Thisfileisused to communicate the authorization data from 
xdm to the Server, using the -auth server command-line option. 

It should be kept in a directory that is not world-writable as it 
could easily be removed, disabling the authorization mecha¬ 
nism in theserver. 

If set to false, disables the use Of the unsecureGreeting in the 
login window. See the subsection "Authentication W idget." 

T he default is true. 

The number of the signal xdm sends to reset the server. 

See the subsection "Controlling the Server." The default is i 
(sighup). 

The number of the signal xdm sends to terminate the server. See 
thesubsection "Controlling the Server." T he default is is 
(sigterm). 
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DisplayManager.DI SPLAY. 
resetForAuth 


DisplayManager.DI SPLAY. 
userAuthDir 


Theoriginal implementation of authorization in the sample 
server reread theauthorization fileat server reset time, instead 
ofwhen checking the initial connection. As xdm generates the 
authorization information just before connecting to the 
display, an old server would not get up-to-date authorization 
information. This resource causes xdm to send sighup to the 
server after setting up the file causing an additional server reset 
to occur, during which time the new authorization information 
will be read. The default istaise, which will work for all M IT 
servers. 

When xdm isunableto write to theusual user authorization file 
(shome/ .xauthority), it creates a unique fi lename in this 
directory and points the environment variable xauthority at 
the created file. It uses /tmp by default. 


CONFIGURATION FILE 

First, the xdm configuration file should beset up. M ake a directory (usually <xRoot>/i±b/xi i /xdm, where <XRoot> refers to the 
root of theXll install tree) to contain all of the relevant files. In the examples that follow, /usn/xi i R6 isused as the value of 
<XRoot>. 

H ere is a reasonable configuration file which could be named xdm-contig: 

DisplayManager.servers: /usr/XI1R6/lib/X11/xdm/Xservers 
DisplayManager.errorLogFile: /usr/X11R6/lib/X11/xdm/xdm-errors 
DisplayManager*resources: /usr/X11R6/lib/X11/xdm/Xresources 
DisplayManager*startup: /usr/X11R6/lib/X11/xdm/Xstartup 
DisplayManager*session: /usr/XI1R6/lib/X11/xdm/Xsession 
DisplayManager.pidFile: /usr/XI1R6/lib/X11/xdm/xdm-pid 
DisplayManager. 0.authorize: true 
DisplayManager*authorize: false 

N ote that this file mostly contains references to other files. N otealso that some of the resources are specified with * 
separating the components. These resources can be made unique for each different display, by replacing the* with the 
display name, but normally this is not very useful. See the "Resources" section for a complete discussion. 

XDMCP ACCESS CONTROL 

The database file specified by theDispiayManager.accessFiie provides information which xdm uses to control access from 
displays requesting XD M CP service. This file contains three types of entries: entries that control the response to Direct and 
Broadcast queries, entries that control theresponseto indirect queries, and macro definitions 

The format of the Direct entries is simple, either a hostname or a pattern, which is distinguished from a hostname by the 
inclusion of one or more metacharacters (* matches any sequence of 0 or more characters, and ? matches any single 
character) which are compared against the hostname of the display device. If the entry isahostname, all comparisons are 
doneusing network addresses, so any namewhich converts to thecorrect network addressmay be used. For patterns, only 
canonical hostnames are used in the comparison, 93 ensure that you do not attempt to match aliases. Preceding either a 
hostname or a pattern with a ! character causes hosts that match that entry to be excluded. 

An indirect entry also contains a hostname or pattern, but follows it with a list of hostnames or macros to which indirect 
queries should be sent. 

A macro definition contains a macro name and a list of hostnames and other macrosthat the macro expands to. T 0 
distinguish macrosfrom hostnames, macro names start with a%character. Macros may be nested. 

indirect entries may al so specify to have xdm run chooser to offer a menu of hosts to connect to. See the subsection 

"chooser." 
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When checking access for a particular display host, each entry isscanned in turn and the first matching entry determinesthe 
response. Direct and Broadcast entries are ignored when scanning for an indirect entry and vice versa. 

Blank lines are ignored, # is treated as a comment delimiter causing the rest of that line to be ignored, and \newiine causes the 
newline to be ignored, allowing indirect host lists to span multiple lines. H ereisasamplexaccess file 
# 

# Xaccess - XDMCP access control file 

# 

# 

# Direct/Broadcast query entries 

# 

lxtra.lcs.mit.edu # disallow direct/broadcast service for xtra 
bambi.ogi.edu # allow access from this particular display 
.lcs.mit.edu # allow access from any display in LCS 
# 

# Indirect query entries 

# 

%HOSTS expo.lcs.mit.edu xenon.lcs.mit.edu \ 

excess.lcs.mit.edu kanga.lcs.mit.edu extract.lcs.mit.edu xenon.lcs.mit.edu #force extract to contact xenon 
lxtra.lcs.mit.edu dummy #disallow indirect access 
.lcs.mit.edu %HOSTS #all others get to choose 

chooser 

For X terminals that do not offer a host menu for use with Broadcast or indirect queries, the chooser program can do this 
for them. In the xaccess file specify chooser as the first entry in the indirect host list, chooser will send a Query request to 
each of the remaining hostnames in the list and offer a menu of all the hosts that respond. 

The list may consist of the word broadcast, in which case chooser will send a Broadcast instead, again offering a menu of all 
hosts that respond. N otethat on some operating systems, U D P packets cannot be broadcast, so this feature will not work. 

Example xaccess file using chooser: 

extract.lcs.mit.edu CHOOSER %HOSTS #offer a menu of these hosts 
xtra.lcs.mit.edu CHOOSER BROADCAST #offer a menu of all hosts 

The program to use for chooser is specified by theDispiayManager.Di splay .chooser resource For more flexibility at this step, 
the chooser could be a shell script, chooser is the session manager here it is run instead of a child xdm to manage the display. 

Resources for this program can be put into the file named by DispiayManager.Di splay .resources. 

When the user selects a host, chooser prints the host chosen, which is read by the parent xdm, and exits, xdm closes its 
connection to theX server, and the server resets and sends another indirect XDMCP request, xdm remembers the user's 
choice (for DispiayManager. choiceTimeout seconds) and forwards the request to the chosen host, which starts a session on that 
display. 

LOCAL SERVER SPECIFICATION 

The resourceDispiayManager.servers givesaserver specification or, if the values starts with a slash (/), the name of a file 
containi ng server specifications, one per line. 

Each specification indicates a display which should constantly be managed and which is not using XD M CP. This method is 
used typically for local servers only. If the resource or the file named by the resource is empty, xdm will offer XD M CP service 
only. 

Each specification consists of at least three parts: a display name, a display class, a display type, and (for local servers) a 
command line to start the server. A typical entry for local display number 0 would be 


:0 Digital-QV local /usr/X11R6/bin/X :0 
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The display types are 

Local local display: xdm must run theserver 

Foreign remote display: xdm opens an X connection to a running server 

The display name must be something that can be passed in the -display option to an X program. This string is used to 
generate the display-specific resource names, so be careful to match the namesffor example, use -.e sun-cG3 local /usr 
/xiiR6/bin/x :0 instead of locaihostna Sun-CG3 local /usr/xiiR6/bin/x :0 if your other resources are specified as 
DispiayManager._0. session). The display class portion isalso used in the display-specific resources, as the class of the 
resource. This is useful if you have a large collection of similar displays (such as a corral of X terminals) and would I ike to set 
resources for groups of them. When using XDM CP, the display is required to specify the display class, so the manual for 
your particular X terminal should document the display classstring for your device. If it doesn't, you can run xdm in debug 
mode and look at the resource strings that it generates for that device, which will include the class string. 

When xdm starts a session, it sets up authorization data for the server. For local servers, xdm passes -auth filename on the 
server's command line to point it at its authorization data. For XDM CP servers, xdm passes the authorization data to the 
server viatheAccept XDM CP request. 

RESOURCES FILE 

The xresources fi le is loaded onto the displ ay as a resource database usi ng xrdb. As the authentication widget reads this 
database before starting up, it usually contains parameters for that widget: 

xlogin*login.translations: #override\ 

Ctrl<Key>R: abort-display()\n\ 

<Key>F1: set-session-argument(failsafe) finish-field()\n\ 

<Key>Return: set-session-argument() finish-field() 
xlogin*borderWidth: 3 
xlogin*greeting: CLIENTHOST 
#ifdef COLOR 

xlogin*greetColor: CadetBlue 
xlogin*failColor: red 
#endif 

Please note the translations entry; it specifies a few new translations for the widget that allow users to escape from the default 
session (and avoid troubles that may occur in it). N otethat if#override is not specified, the default translations are removed 
and replaced by the new value, not a very useful result as some of the default translations are quite useful (such as«ey>: 
insert-char o, which responds to normal typing). 

Thisfile may also contain resources for the setup program and chooser. 

SETUP PRO GRAM 

Thexsetupfileisrun after the server is reset, but before the Login window is offered. The file is typically a shell script. It is 
run as root, so you should be careful about security. This is the place to change the root background or bring up other 
windows that should appear on the screen along with the Login widget. 

In addition to any specified by DispiayManager.exportust, the foil owing environment variables are passed: 
display Theassociated display name 

PATH The value Of DisplayManager.DI SPLAY .systemPath 

SHELL The value Of DisplayManager.DI SPLAY .systemShell 

xauthority M ay beset to an authority file 

Note that si nee xdm grabs the keyboard, any other windows will not beableto receive keyboard input. They will beableto 
interact with the mouse, however; beware of potential security holes here. If DisplayManager.DI splay .grabserver is set, xsetup 
will not beableto connect to the display at all. Resources for this program can be put into the file named by 
DisplayManager.DI SPLAY.resources. 
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H ere is a sample xsetup script: 

#!/bin / sh 

# Xsetup 0 - setup script for one workstation 
xcmsdb </usr/XI1R6/lib/monitors/alex.0 

xconsole -geometry 480x130-0-0 -notify -verbose -exitOnFail & 


AUTHENTICATION WIDGET 


The authentication widget reads an am ^password pair from the keyboard. Nearly every imaginable parameter can be 
controlled with a resource. Resources for this widget should be put into the file named by DispiayManager.Di splay .resources. 
All of these have reasonable default values, so it is not necessary to specify any of them. 


xlogin.Login.width, 
xlogin.Login.height, 
xlogin.Login.x, 
xlogin.Login.y 
xlogin.Login.foreground 
xlogin.Login.font 
xlogin.Login.greeting 

xlogin.Login.unsecureGreeting 


xlogin.Login.greetFont 
xlogin.Login.greetColor 
xlogin.Login.namePrompt 


xlogin.Login.passwdPrompt 

xlogin.Login.promptFont 
xlogin.Login.promptColor 
xlogin.Login.fail 

xlogin.Login.failFont 
xlogin.Login.failColor 
xlogin.Login.failTimeout 

xlogin.Login.translations 


The geometry of the Login widget is normally computed 
automatically. If you wish to position it elsewhere, specify each 
of these resources. 

The color used to display the typed-in username. 

Thefont used to display thetyped-in username. 

A string which identifiesthiswindow. The default isx window 

System. 

When X authorization is requested in the configuration file 
for this display and none is in use, this greeting replaces the 
standard greeting. T he default isThis is an unsecure session. 
Thefont used to display the greeting. 

The color used to display the greeting. 

The string displayed to prompt for a username, xrdb strips 
trailingwhitespacefrom resource values, so to add spaces at 
theend of the prompt (usually a nice thing), add spaces 
escaped with backslashes. The default is Login:. 

T he string displayed to prompt for a password. T he default is 
Password:. 

Thefont used to display both prompts 
The color used to display both prompts. 

A message that isdisplayed when the authentication fails. The 
default is Login incorrect. 

Thefont used to display thefailure message. 

Thecolorused to display the failure message. 

T he number of seconds that thefai lure message is displayed. 
The default is 30 . 

This specifies the translations used for the login widget. Refer 
to theX T oolkit documentation for a complete discussion on 
translations. T he default translation table is 


Ctrl<Key>H 

Ctrl<Key>D 

Ctrl<Key>B 

Ctrl<Key>F 

Ctrl<Key>A 

Ctrl<Key>E 


delete-previous-character() \n\ 
delete-character() \n\ 
move-backward-character() \n\ 
move-forward-character() \n\ 
move-to-begining() \n\ 
move-to-end() \n\ 
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T he actions that are supported by the widget are 

delete-previous-character 

delete-character 

move-backward-character 

move-forward - character 

move-to-begining 

move-to-end 
erase-to-end-of-line 
erase-line 
finish-field 


abort-session 
abort-display 


restart-session 


insert-char 

set-session-argument 

allow-all-access 


Ctrl<Key>K 

erase-to-end-of-line() \n\ 


Ctrl<Key>U 

erase-lined \n\ 


Ctrl<Key>X 

erase-lined \n\ 


Ctrl<Key>C 

restart-sessiond \n\ 


Ctrl<Key>nn 

abort-session/) \n\ 


<Key>BackSpace 

delete-previous-character() 

\n\ 

<Key>Delete 

delete-previous-character/) 

\n\ 

<Key>Return 

finish-field/) \n\ 


<Key> 

insert-char/) \ 



E rases the character before the cursor. 

E rases the character after the cursor. 

M oves the cursor backward. 

M oves the cursor forward. 

(Apologies about the spelling error.) M oves the cursor to the 
beginning of the editable text. 

M oves the cursor to the end of the editable text. 

E rases all text after the cursor. 

Erases the entire text. 

If the cursor isin thename field, proceedsto the password field; 
if the cursor isin thepassword field, checks the current name/ 
password pair. If the name/password pair is valid, xdm starts the 
session. Otherwise, thefailure message is displayed and the 
user isprompted again. 

Terminates and restarts the server. 

T erminates the server, disabling it. Thisaction isnot accessible 
in the default configuration. There are various reasons to stop 
xdm on asystem console, such as when shutting the system 
down, when usi ng xdmsheii, to start another type of server, or 
to generally access the console. Sending xdm a sighup will 
restart the display. See the subsection "C ontrolli ng XDM ." 
Resets theX server and starts a new session. This can be used 
when the resources have been changed and you want to test 
them or when the screen has been overwritten with system 
messages. 

I n serts th e ch aracter typed. 

Specifies a single word argument that is passed tothesession at 
startup. See the subsection "Session Program.'' 

D isables access control in the server. This can be used when 
the .xauthority file cannot be created by xdm. Bevery careful 
using this; it might be better to disconnect the machine from 
the network before doing this 


STARTUP PROGRAM 

Thexstartup file istypically a shell script. It isrun as root and should bevery careful about security. This is the place to put 
commands that add entries to /etc/utmp(thesessreg program may be useful here), mount users' home directories from file 
servers, display the message of the day, or abort the session if logi ns are not al lowed. 
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In addition to any specified by DispiayManager.exportList, the following environment variables are passed: 


DISPLAY 

Theassociated display name 

HOME 

The initial working directory of the user 

USER 

The username 

PATH 

The value Of DisplayManager.DI SPLAY .systemPath 

SHELL 

The value Of DisplayManager.DI SPLAY .systemShell 

XAUTHORITY 

M ay be set to an authority file 


N o arguments are passed to the script, xdm waits until this script exits before starting the user session. If the exit value of this 
script is non-zero, xdm discontinues the session and starts another authentication cycle. 

The sample xstartup file shown here prevents login while the file /etc/noiogin exists. Thus, this is not a complete example, 
but simply a demonstration of the availablefunctionality. 

H ere i s a sam pi e xstartup scri pt: 

#!/bin/sh 
# 

# Xstartup 

# 

# This program is run as root after the user is verified 

# 

if [ -f /etc/nologin ]; then 
xmessage -file /etc/nologin 
exit 1 
fi 

sessreg -a -1 $DISPLAY -x /usr/X11R6/lib/xdm/Xservers $USER 
/usr/XI1R6/lib/xdm/GiveConsole 
exit 0 

SESSION PROGRAM 

Thexsession program is the command that is run as the user's session. It is run with the permissions of the authorized user. 
In addition to any specified by DispiayManager.exportList, the foil owing environment variables are passed: 


DISPLAY 

Theassociated display name 

HOME 

T he initial working directory of the user 

USER 

The username 

PATH 

The value Of DisplayManager.DI SPLAY .userPath 

SHELL 

T he user's default shell (from getpwnam) 

AUTHORITY 

M ay be set to a nonstandard authority file 

KRB5CCNAME 

M ay be set to a Kerberos credentials cache file 


At most installations, xsession should look in shome for afilexsession, which contains commands that each user would like 
to use as a session, xsession should also implement a system default session if no user-specified session exists. Seethe 
subsection "Typical U sage." 

An argument maybe passed to this program from the authentication widget using the set-session-argument action. This can 
be used to select different styles of session. One good use of this feature is to allow the user to escape from the ordinary 
session when it fails This allows users to repair their own .xsession if it fails, without requiring administrative intervention. 
Theexamplefollowingdemon strates th i s f eatu re. 

Thisexample recognizes thespecial failsafe mode, specified in the translations in thexresources file to provide an escape 
from the ordinary session. It also requires that the .xsession file be executable so you don't have to guess what shell it wants 
to use. 
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#!/bin/sh 
# 

# Xsession 

# 

# This is the program that is run as the client 

# for the display manager, 
case $# in 

1 ) 

case $1 in 
failsafe) 

exec xterm -geometry 80x24-0-0 

esac 

esac 

startup=$HOME/.xsession 
resources=$HOME/.Xresources 
if [ -f "$startup" ]; then 
exec "$startup" 
else 

if [ -f "$resources" ]; then 
xrdb -load "$resources" 
fi 

twm & 

xman -geometry +10-10 & 

exec xterm -geometry 80x24+10+10 -Is 

fi 

The user's .xsession file might look something like the following example Don't forget that the file must have execute 
permission. 

#!/bin/csh 

# no -f in the previous line so .cshrc gets run to set $PATH 
twm & 

xrdb -merge "$H0ME/.Xresources" 
emacs -geometry +0+50 & 
xbiff -geometry -430+5 & 
xterm -geometry -0+50 -Is 

RESET PROGRAM 

Symmetrical with xstartup, thexreset script is run after the user session has terminated. Run as root, it should contain 
commands that undo the effects of commands in xstartup, removing entries from /etc/utmp or unmounting directories from 
file servers. The environment variables that were passed to xstartup are also passed to xreset. 

A sample xreset script: 

#! /bin/sh 

# 

# Xreset 

# 

# This program is run as root after the session ends 

# 

sessreg -d -1 $DISPLAY -x /usr/X11R6/lib/xdm/Xservers $USER 
/usr/XI1R6/lib/xdm/TakeConsole 
exit 0 

CONTROLLING THE SERVER 

xdm controls local servers using POSIX signals, sighup is expected to reset the server, closing all client connections and 
performing other cleanup duties, sigterm is expected to terminate the server. If these signals do not perform the expected 
actions, the resources DisplayManager.DISPLAY. resetSignal and DisplayManager.DISPLAY.termSignal Can Specify alternate 
signals. 
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T o control remote terminals not using XD M CP, xdm searches the window hierarchy on the display and uses the protocol 
request Kiiiciient in an attempt to clean up the terminal for the next session. This may not actually kill all of theclients, as 
only those which have created windows will be noticed, xdmcp provides a more sure mechanism; when xdm closes its initial 
connection, the session isover and the terminal is required to close all other connections 

CONTROLLING xdm 

xdm responds to two signals sighup andsiGTERM. When sent asiGHUP, xdm rereads the configuration file the access control file, 
and the servers file. For the servers file it notices if entries have been added or removed. If a new entry has been added, xdm 
starts a session on the associated display. Entries that have been removed are disabled immediately, meaning that any session 
in progress will determinated without notice and no new session will be started. 

When sent a sigterm, xdm terminates all sessions in progress and exits. This can be used when shutting down the system. 

xdm attempts to mark its various subprocesses for ps(l) by editing the command-line argument list in place. Because xdm can't 
allocate additional space for this task, it is useful to start xdm with a reasonably long command linefusing the full pathname 
should be enough). Each process which isservicing a display is marked -display. 

OTHER POSSIBILITIES 

You can use xdm to run a single session at a time, using the 4.3 init options or other suitable daemon by specifying the server 
on the command line: 

xdm -server ":0 SUN-3/60CG4 local /usr/X11R6/bin/X :0" 

Or you might have a file server and a collection of X terminals. The configuration for this is identical to that of the preceding 
sample, except the xservers filewould look likethis: 

extol:0 VISUAL-19 foreign 

exalt:0 NCD-19 foreign 

exploded NCR-TOWERVIEW3000 foreign 

This directs xdm to manage sessions on all three of these terminals See the subsection "Controlling xdm" for a description of 
using signals to enable and disable these terminals in a manner reminiscent of init(8). 

LIMITATIONS 

One thing that xdm isn't very good at doing is coexisting with other window systems. T o use multiple window systems on the 
same hardware, you’ll probably be more interested in xinit. 

FILES 

<XRoot>/lib/X11/xdm/xdm-config 
$HOME/.Xauthority 
<XRoot>/lib/X11/xdm/chooser 
<XRoot>/bin/X11/xrdb 
<XRoot>/bin/X11/X 
<3(Root>/bin/X11 /xterm 
<XRoot>/lib/X11/xdm/A<display>-<suffix> 

/tmp/K5C<display> Kerberos 

N ote: <xRoot> refers to the root of theX11 install tree 

See Also 

X(l), xinit(l), xauth(l), Xsecurity(l), sessreg(l), Xserver(l) 

X Display Manager Control Protocol 


The default configuration file 

User authorization file where xdm stores keys for clients to read 

The default chooser 

The default resource database loader 

The default server 

The default session program and failsafe client 
The default place for authorization fi les 
Credentials cache 
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AUTHOR 

Keith Packard (M IT X Consortium) 


X Version 11 Release 6 


xdpyinfo 

xdpyinfo — D isplay information utility forX 

SYNOPSIS 

xdpyinfo [-display di spl ayname] [-queryExtensions] [-ext extension-name] 

DESCRIPTION 

xdpyinfo is a utility for displaying information about an X server. It is used to examine the capabilities of a server, the 
predefined values for various parameters used in communicating between clients and the server, and the different types of 
screens and visuals that are available. 

By default, numeric information (opcode, base event, base error) about protocol extensions is not displayed. This informa¬ 
tion can beobtained with the -queryExtensions option. U se of this option on servers that dynamically load extensions will 
likely cause all possible extensions to be loaded, which can be slow and can consume significant server resources. 

D etailed information about a particular extension is displayed with the -ext extensionName option. If extensionName is all, 
information about all extensions supported by both xdpyinfo and theserver isdisplayed. 

ENVIRONMENT 

display T o get the default host, display number, and screen 

SEE ALSO 

x(l), xwininfo(l), xprop(l), xrdb(l) 

AUTHOR 

Jim Fulton (M IT X Consortium) 

X Verson 11 Release 6 


Xf86_Accel 

xF86_Accei—Accelerated X W indow System servers for U NIX on x86 platforms with an S3, M ach8, M ach32, M ach64, 
P9000, AGX, ET4000/W 32, or 8514/A accelerator board 

SYNOPSIS 

XF86_S3 [:displaynumber] [ option ] ... 

XF86__Mach8 [: displaynumber] [ option ] ... 

XF86_Mach32 [idisplaynumber] [ option ] ... 

XF86_Mach64 [idisplaynumber] [ option ] ... 

XF86__P9000 [idisplaynumber] [ option ] ... 

XF86_AGX [idisplaynumber] [ option ] ... 

XF86_W32 [idisplaynumber] [ option ] ... 

XF86_8514 [idisplaynumber] [ option ] ... 
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DESCRIPTION 

xf86_s3 is an 8-bit PsaidoColor, 16-bit TrueColor and 24-bit TrueColor server for S3 graphic accelerator boards. N ote, 16- 
bit and 24-bit operation is not supported on all S3 accelerator boards. Refer to readme.S3 for details of which boards are 
supported at which depths. 

xF86_Mach8 is an 8-bit Pseudocolor server for ATI M ach8 graphic accelerator boards. 

xF86_Mach32 is an 8-bit PsudoC olor and 16-bit T rueC olor server for AT I M ach32 graphic accelerator boards. N ote, 16-bit 
operation is not supported on all M ach32 accelerator boards. 

xF86_Mach64 is an 8-bit Pseudocolor, 16-bit T rueColor, and 24-bit T rueC olor server for ATI M ach64 graphic accelerator 
boards. N ote, 16-bit and 24-bit operation is not supported for all RAM DACs. Refer to readme. Mach64 for details of which 
RAM DACs are supported at which depths. 

XF 86 P 9000 is an 8-bit Pseudocolor, 16-bit TrueColor, and 24-bit TrueColor server for Wei tek Power 9000 (P9000) graphic 
accelerator boards. 

xf86_agx is an 8-bit Pseudocolor and 16-bit TrueColor server forAGX/XGA graphic accelerator boards. 

XF86_W32 is an 8-bit Pseudocolor server for ET 4000/W 32, ET 4000/W 32i, and ET 4000/W 32p graphic accelerator boards. 
xf86_8514 is an 8-bit Pseudocolor server for 8514/A graphic accelerator boards. 

These are derived from thex386 server provided with X11R5, and from thex85i4 server developed by Kevin M artin 
(<martin@cs.unc.edu>). 


CONFIGURATIONS 

The servers support the following chi psets: 

XF86_S3 

XF86_Mach8 

XF86_Mach32 

XF86_Mach64 

XF86_P9000 

XF86_AGX 
XF86_W32 
XF868514 


86C911, 86C924, 86C801, 86C805, 86C805i, 86C928, 86C928- P, 
86C732 (Trio32), 86C764 (Trio64), 86C864, 86C868, 86C964, 86C968 
ATI Mach8, ATI Mach32 
ATI Mach32 
AT I Mach64 

Diamond Viper vlb, D iamond Viper pci, Orchid P 9000 , and 
some clones (W eitek P 9000 ) 

AGX-010, AGX-014, AGX-015, AGX-016, XGA-1, XGA-2 
ET4000/W32, ET4000/W32i, ET3000/W32p 

IBM 8514 /A and true clones 


For S3, virtual resolutions up to (approximately) 1,152x800 are supported, using (up to) 1M B of display memory (the S3 
uses an internal width of 1,280 except for new revisions of some of the chips, hence 1M B can't support 1,152x900). Physical 
resolutions up to 1,280x1,024 (1,600x1,280 on some cards) are possible using 2M B or more of display memory. (Virtual 
resolution is dependent solely on the amount of memory installed, with the maxi mum virtual width being 2,048, and 
maximum virtual height is4,096.) 

Similar resolutions are supported on theM ach64. Refer to readme. Mach64 for configuration details. 

Similar resolutions are supported on theM ach32. For theM ach32, the maximum virtual width is 1,536, and the maximum 
virtual height is 1,280. 

ForM ach8, the maximum virtual width is 1,024. 

For 8514, the maxi mum resolution is 1,024x768. 

FortheAGX chips, maximum resolution depends upon the chip revision and amount of available display memory. Refer to 
readme. agx for configuration details. 
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For the P9000, the virtual and physical resolutions must be the same. With sufficient memory, resolutions up to 
1,280x1,024 are supported. 

All the servers that support 24-bit visuals do so using a 32-bit per pixel configuration where 8 bits in every 32 bits is unused. 
This needs to betaken into account when calculating the maximum virtual display size that can be supported atthisdepth. 

OPTIONS 

In addition to the normal server options described in the xserver(l) manual page, these servers accept some more command- 
lineswitches, as described in thexFreesefl) man page. 

TheM ach64, M ach32, S3, P9000, and AGX servers now support more than 8-bit color. The M ach32 and AGX servers 
support 16-bit T rueColor and theM ach64, S3, and P9000 servers support 16-and 32-bit T rueColor. The 32-bit T rueColor 
mode only uses 24 bits per pixel for color information (giving you 16 million colors). These modes may be used by 
specifying the-bpp option as specified in thexFree86(l) man page. 

SETUP 

xFree86 uses a configuration file called xF86Contig for its initial setup. 

SeethexF86Contig(4/5) man page for general details. H ere only the parts specific to thexF86_s3, xF86_Mach8, xF86_Mach32, 
xF86_Mach64, XF86_P9O00, xf86_agx, xf86_w32, and xf86_8514 servers are explained. 

Entries for theDevice section in thexF86Config file include the following: 

chipset "name 11 Specifies a chi pset so the correct driver can be used. Possi ble 

chipsets are 

XF86_S3 

S3_generic: (for a standard 10-driven server) 

Mmio_928: (for a memory-mapped 10-driven server on 
86 C 928, 86C 732, 86C 764, 86C 864, 86C 868, 86C 964, and 
86C968 boards) 

xF86_Mach8, Machs (to force the M ach8 server to run on 
M ach32 boards) 

XF86_Mach32, Mach32 
XF86_Mach64, Mach64 
XF86_P9000 

vipenvib (for the D iamond Viper VLB) 
vipenpci (for the D iamond V i per PC I) 
orchidp9000 (for the 0 rchid P9000 and many 
generic P9000-based boards) 

XF86_AGX 

Agx-016 

Agx-015 

Agx-014 

Agx-010 

Xga-2 

Xga-1 


NOTE 


Only the agx- 016 , agx- 015 , agx- 014 , and xga-2 have been tested. Refer to thexGA and AGX -010 section of readme, agx before 
attempting to use the other chipsets. 




Clocks clock 


ClockChip "cl ockchi p-type" 


Ramdac "r amdac-1 ype" 


xf86_Accel 

XF86 W32 

Et4000w32 
Et4000w32i 
Et4000w32i_rev_b 
Et4000w32i_rev_c 
Et4000w32p_rev_a 
Et4000w32p_rev_b 
Et4000w32p_rev_c 
Et4000w32p_rev_d 

XF86_8514 

Ibm8514 

For boards with nonprogrammable clock chips, theclockscan 
be specified here (see xF86Cont ig(4/5)). The P9000 server now 
no longer requires a clocks line It will now work the same 
way as other servers with a programmable clock chip (that is, 
use the clocks as specified in the M odes). N ote, clocks over 
110 M H z are not recommended or supported by the P9000 
server. The M ach64 server also does not require a clocks line 
because the clocks are normally read directly from the video 
card's BIOS. FortheM ach64 server, the clocks given in the 
xF86Contig file are ignored unless the no_bios_ciocks option is 
given (see below). 

For boards with programmable clock chips(exceptwith the 
P9000 and AG X servers), the name of the clock chip is given. 
Possible values for the S3 server include "icd 206 ia", 

"ics9161a", "dcs2834", "sc11412", M s3gendac", "s3 sdac", 
"ti3025\ "ti3026\ "ics2595\ "ics5300\ "ics5342" f "ch8391 \ 
"stg1703", and "ibm_rgb5xx". 

This specifies the type of RAM DAC used on the board. Only 
the S3, AGX, and W 32 servers use this. 

Normal— (S3, AG X) C ard does not have one of the other 
RAM D ACsmentioned here. Thisoption isonly required for 
the S3 server if the server incorrectly detects one of those other 
RAM D AC s. The AGX server does not yet auto-detect 
RAM DACs, this isthe default if no RAM DAC is specified. 
Generic— (W 32) T his forces the W 32 server to treat the 
RAM DAC asagenericVGA RAM DAC. 

Att20c490— (S3, AGX) Card has an AT&T 20C490 or AT&T 
20C491 RAM DAC. When thedac_8_bit option is specified, 
these RAM DACs may be operated in 8-bit per RGB mode. It 
also allows 16bpp operation with 801/805/928 boards. True 
AT&T 20C490 RAM DACsshould be autodetected by the S3 
server. This RAM DAC must be specified explicitly in other 
cases. N ote that 8-bit per RGB mode does not appear to work 
with theWinbond 82C490 RAM DACs(which SuperProbe 
identifiesasAT&T 20C492). 16bppworksfinewith the 
W inbond 82C490. TheD iamond SS2410 RAM DAC is 
reported to becompatiblewhen operating in 15bpp mode 
(not 16bpp). TheChrontel 8391 appears to be compatible in 
all modes. 
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Sci5025— (S3, AGX) Card hasaSierra SC 15025 or SC 15026 
RAM D AC. The S3 server has code to autodetect this 
RAMDAC. 

sen 482— (S3) Card has a Sierra SC 11482, SC 11483, or 
SC 11484 RAM D AC. The S3 server has codeto autodetect 
thisRAM DAC. 

sen 485— (S3) Card hasaSierra SC 11485, SC 11487 or 
SC 11489 RAM DAC. The S3 server will detect these 
RAM D ACsasan scii482, so thisoption must be specified to 
take advantage of extra features (they support 16bpp, 15bpp, 
and 8bpp, while the others only support 15bpp and 8bpp). 
Bt485— (S3) Card has a BrookT reeBt485 or Bt9485 
RAM DAC. Thismust be specified if the server fails to detect it. 
Att20c505— (S3) Card has an AT&T 20C505 RAM DAC. 
Thismust be specified either if the server fails to detect the 
20C505, or if the card has a Bt485 RAM DAC and there are 
problems using clocks higher than 67.5M Hz. 

Att20c498— (S3) Card has an AT&T 20C498 or 21C498 
RAM DAC. Thismust be specified if the server fails to detect it. 
Att22c498— (S3) Card has an AT&T 22C498 RAM DAC. 
Thismust be specified if the server fails to detect it. 
ibm_rgb5i4— (S3) Card has an IBM RGB514 RAM DAC.This 
must be specified if the server fails to detect it. 
ibm_rgb524— (S3) Card has an IBM RGB524 RAM DAC.This 
must be specified if the server fails to detect it. 
ibm_rgb525— (s3) Card has an IBM RGB 525 RAM DAC. This 
must be specified if the server fails to detect it. 
ibm_rgb528— (S3) Card has an IBM RGB528 RAM DAC.This 
must be specified if the server fails to detect it. 

Stg1700— (S3) Card has an STG1700 RAMDAC. T his must be 

specified if the server fails to detect it. 

Stg1703—(S3) Card has an STG1703 RAMDAC. T his must be 

specified if theserver faiIsto detect it. 

S3gendac— (S3) Card has an S3 86C708 GEN DAC. This 
RAMDAC does not support 8-bit per RG B mode (don't 
specify the dac_8_bit option). It allows 16bpp operation with 
801/805 boards. There is currently no autodetection for this 
RAMDAC. 

S3_sdac— (S3) Card has an S3 86C716 SDAC RAM DAC. 
Thismust be specified if the server fai Is to detect it. 
ics5300— (S3) Card has an ICS5300 RAM DAC. Thismust be 
specified if the server fails to detect it (the server will recognize 
this as an S3 GEN DAC which is OK). 
ics5342— (S3) Card has an ICS5342 RAM DAC. Thismust be 
specified if the server fails to detect it (the server will recognize 
thisasan S3 SDAC which isOK). 

Ti3020— (S3) Card h as a TI ViewPointTi3020 RAM DAC. 
Thismust be specified if the server fai Is to detect theT i3020. 

N ote that pixel multiplexing will beused for this RAM DAC if 
any mode requi res a dot clock higher than 70M Hz. 



IOBase i oaddress 

H3025 — (S3) Card h as a T1 ViewPointTi3025 RAM DAC. 
This must be specified if the server fails to detect the T i3025. 
Ti3026— (S3) Card h as a T1 ViewPointTi3026 RAM DAC. 
This must be specified if the server fails to detect the T i3026. 
Bt48i — (AG X) Card has a BrookT ree Bt481 RAM DAC. 

Bt482— (AG X) Card has a BrookT ree Bt482 RAM DAC. 

Here dual dac— (AGX) Card (FI ercules Graphite Pro) has 
both the 84-pin (Bt485 or AT&T20C505) and 44-pin (Bt481 
or Bt482) RAM D AC s installed. 

Herc_smaii_dac — (AGX) Card (H erculesGraphitePro) has 
only the 44-pin (Bt481 or Bt482) RAM DAC installed. 
Specifies the base address for extended 10 registers. Thisis 
only used by theAGX server, and by the P9000 server for the 
Viper PCI. For details of how to use it, refer to readme, agx and 

README.P9000. 

MemBase memaddress 

Specifies the hard-wired part of the linear framebuffer base 
address. This option is only used by the P9000, S3, Mach64, 
and M ach32 servers (and only when using a linear 
framebuffer). For the S3 server, thehard-wired part is the high 
10 bits of the 32-bit address(that is, memaddress ismasked with 
0XFFC0000O). N ote: This should not be required for the 864 
and 964 chips where the enti re framebuffer address is software- 
selectable Also, note that in versions prior to 3.1.1, the S3 
server used only the top 6 bits of memaddress, and oRed it with 
0x3000000. T o get the same behavior, or 0x3000000 with the 
value given previously. For the M ach32 server, the mask is 
0XF8000000 (except for PCI cards, where the membase setting is 
ignored). 

This option must be specified with the P9000 server. With 
local busDiamondVipersthevalueof memaddress can be 
either 0x80000000,0x20000000, or 0xa0000000. T he default is 

0x80000000. Any value should work as long as it does not 
conflict with another device already at that address. For the 
Viper PCI, refer to readme.P9000. FortheOrchid P9000, the 
base address may be 0x00000000,0x00000000, or0xE0000000, 
and must correspond the board's jumper setting. N ote Thes3 
server will normally probe for this address automatically. 

Setti ng this option overrides that probe. T his is not normally 
recommended because the fai lure of the server's probe usually 
indicates problems in using the linear framebuffer. 


NOTE 


T he M ach64 server requires the memory aperture. For ISA bus video cards, this means that the aperture must be enabled 
and the aperture address must be set to a value I ess than 16M B (which meansthat, on ISA systemsonly.tousetheM ach64 
server you must have 12M B of main memory or less). N ormally the M ach64 server will use predefined values for this 
address, but setting this option will override the predefined address. 

TheM ach32 server should not require the use of this option under normal circumstances. 
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COPBase baseaddress 


Instance i nst ance 


S 3 MClk me me I k 


S 3 MNAdj ust M N 
S 3 RefClk r ef cI k 


T his sets the coprocessor base address for the AG X server. 
Refer to readme. agx for details. 

ThissetstheXGA instance number for the AGX server. Refer 
to README.agx for details. 

This allows the video card's memory clock value to be 
specified. This is only used for 805i, 864 and T rio32/64 cards, 
and the value should not normally be given here for cards with 
an S3 Gendac or Trio64. This entry doesn't change the card's 
memory clock, but it is used to calculate the D RAM timing 
parameters. For further details refer to readme.S 3 . 

This allows some memory timing parameters to be adjusted 
for DRAM cards. For further details refer to readme.S 3 . 

This allows the P LL reference clock to be specified. This may 
be requi red for some cards that use the IB M RG B 5xx 
RAM DACs.Thevalueisin MHz. For further details refer to 

README.S 3 . 


Option flags may be specified in either the Device section or the Display subsection of thexF 86 Config file 

option "opt i onstri ng” Allows the user to select certain options provided by the 

drivers. Currently thefollowing strings are recognized: 
Nomemaccess— (S3) D isable direct access to video memory. 

This option is ignored for the 864 and 964 chips 
Noaccei— (AGX, P9000) D isable hardware acceleration for the 
P9000, and disables thefont cache with theAGX. 
vram_i28— (AGX, P9000) When memory probe fails, use if 
you have 128Kx8 VRAM s. 

vram_ 256 — (AGX, P9000) When memory probe fails, use if 
you don't have 128Kx8 VRAM s. 

Noiineai — (S3 and M ach32) D isable use of a I inear-mapped 
framebuffer. 

Ti 3020 _curs— (S3) EnablestheTi3020'sinternal HW cursor. 
(D efault) 

No_ti 3020 _curs— (S3) D i sables the Ti 3020’s internal HW 
cursor. 

sw_cursor— (S3, M ach32, M ach64, P9000, AGX) D isablethe 
hardware cursor. 

oac_ 8 _bit— (S3, M ach32, M ach64, AGX) Enables 8-bit per 
RGB. Currently only supported with theTi3020/5/6, Bt 485 , 

AT&T 20 C 505 , AT&T 20 C 490 / 1 , Sierra SC 15025 / 6 , AT&T 20 C 498 and 

stgi700/3, ibm rgb 5 xx (S3 server), Bt 48 i and Bt 482 (AGX 
server), ATi68875/nc34075/Bt885 (M ach32 server), ATI68875, 
TLC 34075 , ATI 68860 , ATI 68880 , STGI 702 , and STGI 703 (M ach64 
server) RAM DACsThisisnow set by default in thes3 server 
when oneof the preceding RAM D ACsotherthan the 
AT&T 20 C 490 / 1 is used. 

Dac_ 6 _bit— (S3) Force 6-bit per RGB in cases where 8-bit 
mode would automatically be enabled. 
sync_on_green— (S3, P9000) E nables generation of sync on the 
green signal on cards with Bt485, AT&T20C505, Ti 3020 /s /6 or 
ibmrgb 5 xx RAM D ACs. N ote: Although these RAM D ACs 
support sync_on_green, it won't work on many cards because 
of theway they are designed. 
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Power_saver— (S3 and M ach64) This option enable the server 
to use the power-saving feature of VESA D PM S-compatible 
monitors. The suspend level is currently only supported for the 
M ach64 and for the 732 ,764,864,868,964,968 S3 chips. Refer 
to the xF86Cont ig(4/5) manual page for detai Is of how to set 
the timeouts for the different levels of operation. This option 
is experimental. 

intei_gx— (M ach32) Sets the hard-wi red offset forthelinear 
framebuffer correctly for the Intel GX Pro cards. This option 
is equivalent to setting themembase to 0 x 78000000 . 
spea_mercury— (S3) Enables pixel multiplex support for SPEA 
M ercury cards (928 +Bt485 RAM D AC). For these cards, pixel 
multiplexing isrequired in order to use dot clocks higher than 
67.5 M H zand to access more than 1M B of video memory. 
Pixel multiplexi ng is currently supported only for 
noninterlaced modes, and modes with a physical width no 
smaller than 1,024. 

stb_pegasus— (S3) Enables pixel multiplex support for STB 
Pegasus cards (928 +Bt485 RAM DAC). For these cards, pixel 
multiplexing isrequired in order to use dot clocks higher than 
67.5 MHz. Pixel multiplexing is currently supported only for 
noninterlaced modes, and modes with a physical width no 
smaller than 1,024. 

number_nine — (S3) Enables pixel multiplex support for 
NumberNineGXelevel 10,11,12 cards (928 +Bt485 
RAM DAC). For these cards, pixel multiplexing isrequired in 
order to use dot clocks higher than 85M Hz. Pixel multiplexing 
is currently supported only for noninterlaced modes, and 
modes with a physical width no smaller than 800. Thisoption 
is also required for some other N umber N ine cards (for 
example, gxe64 and GXE64pro). 
diamond— (S3) This option may be required for some 
D iamond cards (in particular, the 964/968 VRAM cards). 
eisa_wi 00 Opro — ( S3) E nables support for the E LSA W inner 
1000 PRO. Thisoption is not usually required because the 
board can beautodetected. 

eisa_wi 00 Oisa— (S3) E nables support for the E LSA Winner 
1000 ISA. Thisoption is not usually required because the 
board can beautodetected. 

eisa_w 2000 pro— ( S3) E nables support for the E LSA W inner 
2000 PRO. Thisoption is not usually required because the 
board can beautodetected. 

pci_hack— (s3> Enables a workaround for problems seen with 
some PC I 928 cards on machines with a buggy SM C U ART. 
s3_964_bt485_vcik— (S3) E nables a workaround for possible 
problems on cards using the 964 and Bt485. 
genoa, stb, hercules, Or number_nine,— (S3) T hese options may 
be used to select different defaults for the blank delay settings 
for untested cards with IBM RGB5xx RAM D ACsto avoid 
pixel-wrapping problems. 
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siow_vram— (s3> Adjusts the VRAM timings for cards using 
slow VRAM . This is required for some D iamond Stealth 64 
VRAM and H erculesTerminator64 cards. 

Fastj/ram— (s3> Adjusts the VRAM timings for faster VRAM 
access. There will be display errorsand pixel garbage if your 
card can't support it. 

siow_dram_ref resh— (S3) Adjusts the D RAM refresh for cards 
with slow DRAM to avoid lines of corrupted pixels when 
switching modes. 

No_biock_write— (Mach64> D isables the block write mode on 
certain typesofVRAM M ach64 cards. If noise or shadows 
appear on thescreen, thisoption should remove them. 
Biock_write— (M ach64) Enables the block write mode on 
certain typesofVRAM Mach64 cards. N ormally the M ach64 
server will automatically determine if the card can handle 
block write mode, but thisoption will override the probe 
result. 

No_bios_ciocks— (M ach64) T he M ach64 server normally 
reads the clocks from the bios. Thisoption overrides thebi os 
clocks and forces the server to use the clocks given in the 

XF86Config file. 

There are also numerous tuning options for the AG X server. 
Refer to readme. agx for details. 

N otethat xFree86 has some internal capabilities to determine what hardware it is running on. Thus, normally the keywords 
chipset, clocks, and videoram don't haveto be specified. But there may be occasionswhen this autodetection mechanism 
fails, (for example, too high a load on the machine when you start the server). For cases like this, one should first run the 
server on an unloaded machine look at the results of the autodetection (that are printed out during server startup), and then 
explicitly specify these parameters in the configuration file. It is recommended that all parameters, especially clock values, be 
specified in thexF86Config file. 

FILES 

<XRoot>/bin/XF86 S3 
<XRoot>/bin/XF86 Mach8 
<XRoot>/bin/XF86 Mach32 
<XRoot>/bin/XF86 Mach64 
<XRoot>/bin/XF86 P9000 
<XRoot>/bin/XF86 AGX 
<XRoot>/bin/XF86 W32 
<XRoot>/bin/XF86 8514 
/etc/XF86Config 
<XRoot>/lib/X11/XF86Config 
<XRoot>/lib/X11/doc/README.agx 
<XRoot>/lib/X11/doc/README.P9000 
<XR00t>/lib/X11/doc/README.S3 
<XRoot>/lib/X11/doc/README.W32 


T he 8-, 16-, and 24-bit color X server for S3 

T he 8-bit color X server for M ach8 

The 8- and 16-bit color X server for M ach32 

T he 8-, 16-, and 24-bit color X server for M ach64 

T he 8-, 16-, and 24-bit color X server for the P9000 

The8- and 16-bit color X server for AGX andXGA 

T he 8-bit color X server for ET 4000/W 32 

The 8-bit color X server for IBM 8514 and true compatibles 

Server configuration file 

Server configuration file (secondary location) 

Extra documentation for the AGX server 
Extra documentation for the P9000 server 
Extra documentation for the S3 server 
Extra documentation for the W 32 server 


N ote: <xRoot> refers to the root of the X11 install tree. 
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SEE ALSO 

X(l), Xserver(l), XFree86(l), XF86Conf ig(4/5), xvidtune(l), xdm( 1 ), xf86config( 1) , xinit(l) 

AUTHORS 

In addition to the authors of xFreese the following people contributed major work to this server: Kevin M artin 
(martin@cs. unc.edu), J on T ombs (tombs@xFnee86.org), Rik Faith (f aith@cs. unc. edu). (D id the overall work on the base 
accelerated servers.) 

D avid Dawes (dawes@XFree86.org), D irk H Ohndel (hohndel@XFree86.org), D avid W exelblat (dwex@XFree86.org). (M erged 
their work into xFree86.) 

Jon Tombs (tombs@xFree86.org), David Wexelblat (dwex@xFree86.org), David Dawes (dawes@xFree86.org), Amancio H asty 
(hasty@netcom.com), Robin C Utshaw (robin@XFree86.org), N Orbert D istler (Norbert.Distler@physik.tu-muenchen.de), Leonard 
N . Zubkoff (lnz@dandelion.com), H arald Koenig (koenig@tat.physik.uni-tuebingen.de), Bernhard Bender 
(br@eisa.mhs.compuserve.com), H ans N asten (nasten@everyware.se). (D evelopment and improvement of the s3-specific code.) 

Kevin M artin (martin@cs.unc.edu), Rik Faith (faith@cs.unc. edu), T iago GOns (tiago@comosjn .hobby.nl), FI ans N asten 
(nasten@everyware.se), Scott Laird (lair@midway.uchicago.edu). (D 0/elopment and improvement Of theMach8- and 8514/A- 
specific code.) 

Kevin M artin (martin@cs.unc.edu), Rik Faith (taith@cs.unc.edu), M ike Bernson (mike@mbsun.mib.org), M ark Weaver 
(MarkWeaver@brown.edu), C raig G roeschel (craig@metrolink.com). (D evelopment and improvement Of theMach32-specific code. 

Kevin M artin, (martin@cs.unc.edu). (Development of the Maoh64-specific code.) 

Eri k N ygren (nygren@mit.edu), FI arry Langenbacher (harry@brain. ] pi.nasa.gov), ChrisM ason 

(cimtch@osfmaii.isc.rit.edu), FH enrik H armsen (harmsen@eritei.se). (D evelopment and improvement of the P9O00-specific 
code.) 

FI enry Worth (henry.worth@amaii.amdahi.com). (D evelopment of the AGX specific code.) 

Glenn Lai (gienn@cs.utexas.edu). (Development of the ET 4000 /w 32 -specificcode.) 

See also the xFree86(l) manual page. 

BUGS 

Some S3 cards with Bt485 RAM D AC s are currently restricted to dot-clocks less than 85M Hz. 

TheP9000 server may still have problems with cards other than the D iamond Viper VLB. There may still be problems with 
VGA mode restoration, but these should almost never occur. Using physical resolutions different from thevirtual resolution 
is not supported and is not possible with the P9000. Use at dot-clocks greater than 110M Hzisnot recommended and not 
supported. D iamond claims that 135M Hz is the maximum clock speed, but some of its bt485S are not rated that high. If you 
do not have a 135M H zbt485 on your Viper, contact Diamond tech support and they will send you an RM A number to 
replace the board. Acceleration is being added in slowly. At the present, only copyArea, Movewindow, and DrawLine are 
implemented. Other accelerated features are being tested and may be available in the next release. There seemsto bea 
problem with oivwm when used with xdm and vt switching. The cursor will be messed up when you return to avT if the cursor 
changed while you were in thevr. 

CONTACT INFO 

XFreese source is available from the FTP server ftp.xFree86.org and mirrors. Send e-mail to xFree86@xFree86.org for details. 

xFree86 Verson 3.1.2 
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XF86_Mono 

xF86_Mono — 1-bit nonaccelerated X Window System servers for U N IX on x86 platforms 

SYNOPSIS 

XF86 Mono [idisplaynumber] [ option ] ... 


DESCRIPTION 

xF86_Mono is a 1-bit Stati cG rey server for VGA and SuperVGA cards and for some other monochrome cards. 


CONFIGURATIONS 

T he xF86_Mono server supports the following popular SuperVGA chipsets in monochrome mode 


ATI 
T seng 

Western Digital 

Genoa 

Trident 

NCR 

Compaq 

Oak 

Cirrus 


18800,18800-1, 28800-2, 28800-4, 28800-5, 28800-6, 68800-3, 
68800-6, 68800AX, 68800LX, 88800CX, 88800GX 
ET3000, ET4000, ET4000/W32 

PVGA1, WD90C00, WD90C10, WD90C11, WD90C30, WD90C31, WD90C33 
GVGA 

TVGA8800CS, TVGA8900B, TVGA8900C, TVGA8900CL, TVGA9000 

77C22, 77C22E 

AVGA 

OTI067, OTI077, OTI087 

CLGD5420, CLGD5422, CLGD5424, CLGD5426, CLGD5428, CLGD5429, 
CLGD5430, CLGD5434, CLGD5436, CLGD6205, CLGD6215, CLGD6225, 
CLGD6235, CL6410, CL6412, CL6420, CL6440 


T he xF86_Mono server supports the following monochrome cards and resolutions: 

Sigma L-View, LaserView PLUS (in lbpp mode): 1,664x1,280 

Hyundai HGC-1280: l,280[l,472]xl,024 

Apollo M onochromecard (with ID 9) from Apollo workstations: 

1,280x1,024 

H ercules and compatibles cards 720x348 

Additionally, it supports generic VGA cards with a maximum virtual resolution of (approximately) 800x650. 

On supported SVGA chipsets, xF86_Mono will use up to V 4 of display memory, which yields a maximum virtual resolution of 
(approximately) 1,664x1,260 with 1MB of display memory. xF86_Mono does not support the accelerated functions of the 
supported chipsets. 


OPTIONS 

In addition to the normal server options described in thexserver(l) manual page, xF86_Mono accepts some more command- 
lineswitches, as described in thexFree86(l) man page. 

SETUP 

xFreese uses a configuration file called xF86Contig for its initial setup. 

SeethexF86Contig(4/5) man page for general details. H ere only the xF86_Mono specific parts are explained. 

The Driver entry in screen section of thexF86Config file should beset to vga 2 for VGA and SVGA boards, and mono for non- 
VGA mono boards. If screen sections are present for both of these, the server will start in adual-headed configuration. 
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Entries for theDevice section in thexFseconfig fi le include the followi ng: 


chipset "name" 


Specifies a chipset so the correct driver can be used. Possible 
chipsets for VG A2: 


ATI 
T seng 

Western Digital 


Vgawonder 

Et3000, et4000, et4000w32, et4000w32i, 
et4000w32p 

Pvgal, wd90c00, wd90c10, wd90c30, 
wd90c31, wd90c33 


Genoa 
T rident 

NCR 

Cirrus 


Generic VGA 


Gvga 

Tvga8800cs, tvga8900b, tvga8900c, 
tvga8900cl, tvga9000 
Ncr77c22, ncr77c22e Compaq: cpq avga 
OAK: oti067, oti077, oti087 
Clgd5420, clgd5422, clgd5424, clgd5426, 
clgd5428, clgd5429, clgd5430, clgd5434, 
clgd5436, clgd6205, clgd6215, clgd6225, 
Clgd6235, C16410, C16412, 016420, C16440 
generic 


Possible chipsets for mono: 

Hyundai hgci 280 

Sigma sigmalview 

Apollo apollo9 

H ercules hercules 

MemBase me ma d d r e s s Specifies the base address of the video memory. Thisoption is 

only used fortheSigma LaserViewcards. Valid addresses for 
these cards are 0XA0000, 0 x 00000 , 0 x 00000 , 0 x 00000 , oxE0000.The 
default is 0 xE 0000 . 

Black red green blue Sets the black color to the RG B values specified. T hese values 

must be given as integers in the range 0-63. The default iso 0 
0 .Thisoption isonly valid forthevga 2 screen type. 

white red green blue Sets thewhite color to the RG B values specified. T hese values 

must be given asintegersin the range 0-63. The default is 63 
63 63. Thisoption isonly valid forthevga 2 screen type 

option ■ opt ionst ring" Allows the user to select certain options provided by the 

drivers. Currently thefollowing strings are recognized: 
legend— For Sigma Legend ET4000-based boards. This 
option enables a special clock-selection algorithm used on 
Legend boards, and M U ST be specified for these boards to 
function correctly. 

swap_hibit— For Western Digital/PVGAl chipsets. Some 
Western Digital-based boards requi re the high-order clock- 
select lead to beinverted. Itisnot possi ble for the server to 
determine this information at run-time. If the 9th clock in the 
list of clocks detected by the server is less than 30M hz, this 
option likely needs to beset. 
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Hibit_iow, hibit_high— For Tseng ET 4000 chipsets. With 
someET 4000 cards, the server has difficulty getting the state 
of the high-order clocks select bit right when started from a 
high-resolution text mode. These options allow the correct 
initial state of that bit to be specified. T o find out what the 
correct initial state is, start the server from an 80x25 text 
mode. This option is only needed if the clocks reported by the 
server when started from a high-resolution text mode differ 
from those reported when it is started from an 80x25 text 
mode. 

sciocks— For thePVGAl chipset, the default is4 clocks 
Somecardswith this chipset may support8 clocks. Specifying 
thisoption will allow thedriver to detect and usetheextra 
clocks 

ieciocks— ForTrident tvga8900b and 8900c chipsets. Some 
newer boards using 8900B and 8900c chipsets actually support 
16 clocks rather than the standard 8 clocks. Such boards will 
haveaTCK9002 oncK9004 chip on them. Specifying this option 
will allow the driver to detect and use the extra 8 clocks. 
Powen_saver— Thisoption enables the server to use the power 
savi ng features of V E SA D P M S-compati bl e mon i tors. T he 
suspend level is currently not supported. Refer to the 
xF86Conf ig(4/5) manual page for details of how to set the time¬ 
outs for the different levels of operation. Thisoption is 
experimental. 

secondary— For the hgci 280 and apoiio9 chipsets. Thisoption 
allows theuseof these cardsjumpered to thesecondary 1 / 0 / 
memory address. T hese addresses are 

hgc1280: I/O 0X3B0-0X3BF, mem 0XB0000-0XBFFFF (prim.) 

I/O 0X390-0X39F, mem 0XC8000-0XCFFFF (sec.) 
apollo9: I/O 0X3B0-0X3BF, mem 0XFA0000-0XFDFFFF (prim.) 

I/O 0X3D0-0X3DF, mem 0XA0000-0XDFFFF (sec.) 

xFreese can detect the hgc -1280 on both primary and 
secondary address; for theapoiio card the primary address is 
used by default. 

N otethat xFree86 has some internal capabilities to determine what hardware it is running on. Thus, normally the keywords 
chipset, clocks, and videoram don't haveto be specified. But there may be occasionswhen this autodetection mechanism 
fails, (for example, too high a load on the machine when you start the server). For cases like this one should first run 
xF86_Mono on an unloaded machine look at the results of the autodetection (that are printed out during server startup) and 
then explicitly specify these parameters in the configuration file It is recommended that all parameters, especially clock 
values, be specified in thexF86Config file. 

FILES 

<xRoot>/bin/xF86 Mono T he monochrome X server for VGA, SVGA and other 

monochrome cards 

/etc/xF86Contig Server configuration file 

<xRoot>/iib/xi i /xF86Conf ig Server configuration file 

N ote: <xRoot refers to the root of the X11 install tree 
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SEE ALSO 

X(l), Xserver(l), XFree86(l), XF86Config(4/5), xf86config(l), xvidtune(l), xdm(l), xinit(l) 

BUGS 

There are no known bugs at this time, although we welcome reports e-mailed to the address listed below. 

CONTACT INFO 

xFree86 source isavailablefrom the FT P serverftp.xFree86.org. 

Send e-mail to xFree86@xFree86.org for details. 

AUTHORS 

Refer to thexFree86(l) manual page. 

XFree86 Veraon 3.1.2 


XF86_SVGA 

xf86_svga — N onaccelerated SVG A X W i ndow System servers for U NIX on x86 platforms 

SYNOPSIS 

XF86 SVGA [idisplaynumber] [ option ] ... 


DESCRIPTION 

xf86_svga is an 8-bit Pseudocolor, 16-bit TrueColor and 24-bit T rueColor server for Super VGA cards. It is derived from 
thex386 server provided with xhrs. N ote: 16-bit T rueColor is currently only supported for some Cirrus and ARK chips, and 
24-bit T rueC olor is only supported for some C irrus chips. 


CONFIGURATIONS 


ThexF86_svGA server supports the following popular SuperVGA chipsets in 256-color mode. Virtual resolutions up to 
(approximately) 1152x900 are supported, using (up to) 1MB of display memory. The Western D igital WD 90 C 33 and some of 
the Cirrus chipsets support up to 2M B of display memory and virtual resolutions of 1,280x1,024 and higher. Some of the 
Cirrus chipsets also support 16bpp and 32bpp (truecolor) modeson certain configurations. Some of theARK chipsets 
support 16bpp modeson certain configurations. Generic VGA cards are also supported at 8bpp 320x200 only. 


ATI 
T seng 

Western Digital 

Genoa 
T rident 
NCR 

Cirrus Logic 


ARK 
RealT ek 
Compaq 
Oak 


18800,18800-1, 28800-2, 28800-4, 28800-5, 28800-6, 68800-3, 
68800-6, 68800AX, 68800LX, 88800CX, 88800GX 
ET3000, ET4000, ET4000/W32 

PVGA1, WD90C00, WD90C10, WD90C11, WD90C24A, WD90C30, WD90C31, 

WD90C33 

GVGA 

TVGA8800CS, TVGA8900B, TVGA8900C, TVGA8900CL, TVGA9000 
77C22, 77C22E 

CLGD5420, CLGD5422, CLGD5424, CLGD5426, CLGD5428, 

CLGD5429,CLGD5430, CLGD5434, CLGD5436, CLGD6205, CLGD6215, 

CLGD6225, CLGD6235, CL6410, CL6412, CL6420, CL6440 

ARK1000PV, ARK1000VL, ARK2000PV 

RTG3106 

AVGA 

OTI067, OTI077, OTI087 
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Avance Logic 
Chips& Technology 
MX 

Video7 


AL2101, ALI2301, ALI2302, ALI2308, ALI2401 
65520, 65530, 65540, 65545 
MX68000, MX68010 
HT216-32 


Accelerated support is included for most of the Cirrus chipsets, and for the Western D igital WD 90 C 31 and WD90C33 chipsets. 
Accelerated support for the ET 4000 /W 32 is implemented in a separate server (see xf86_w32(1)). Users of boards based on ATI's 
M ach8, M ach32, and M ach64 chipsets should refer to thexF86_Mach8(l), xF86_Mach32(l) and xF86_Mach64(l) manual pages, 
respectively. 


OPTIONS 

In addition to the normal server options described in thexserver(l) manual page, xf86_svga accepts some more command- 
lineswitches, as described in thexFree86(l) man page. 


SETUP 

xFree86 uses a configuration file called xF86Contig for its initial setup. 

SeethexF86Contig(4/5) man page for general details. H ere only thexF86_svGA specific parts are explained. 

This server requires a screen section in thexF86Config file with the Driver entry set to svga. 

Entries for the Device section in thexFseconfig fileinclude 

chipset “name" Specifies a chipset so the correct driver can be used. Possible 

chipsets are 


ATI 

vgawonder 

T seng 

et3000, et4000, et4000w32, 
et4000w32i, et4000w32p 

Western Digital 

pvgal, wd90c00, wd90c10, wd90c24, 
wd90c30, wd90c31, wd90c33 

Genoa 

gvga 

T rident 

tvga8800cs, tvga8900b, tvga8900c, 
tvga8900cl, tvga9000 

NCR 

ncr77c22, ncr77c22e 

Cirrus Logic 

clgd5420, clgd5422, clgd5424, 
clgd5426, clgd5428, clgd5429, 
clgd5430, clgd5434, clgd5436, 
clgd6205, clgd6215, clgd6225, 
Clgd6235, C16410, C16412, C16420, 

C16440 

RealT ek 

realtek 

ARK 

ark1000pv, ark1000vl, ark2000pv 

Compaq 

cpq_avga 

Oak 

Oti067, oti077, oti087 

Avance Logic 

al2101, ali2301, ali2302, ali2308, 

ali2401 

Chips& Technology 

Ct65520, Ct65530, Ct65540, Ct65545 

MX 

mx 

Video7 

video7 

Generic 

generic 
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option *opt i onstri ng" Allows the user to select certain options provided by the 

drivers. Currently thefollowing strings are recognized: 
legend— For Sigma Legend ET4O00-based boards. This option 
enables a special clock-selection algorithm used on Legend 
boards, and M UST be specified for these boards to function 
correctly. 

swap_hibit— For Western D igital/PVGAl chipsets. Some 
Western Digital-based boards require the high-order cl ock- 
select lead to beinverted. Itisnot possible for the server to 
determine this information at run-time. If the 9th clock in the 
list of clocks detected by the server is less than 30M hz, this 
option likely needs to beset. 

HibitjLow, hibitjiigh— For Tseng ET 4000 chipsets. W ith some 
ET 4000 cards, the server has difficulty getting the state of the 
high-order clocks select bit right when started from a high- 
resolution text mode. T heseoptionsallow thecorrect initial 
state of that bit to be specified. To find out what the correct 
initial state is, start the server from an 80x25 text mode. This 
option is only needed if the clocks reported by the server when 
started from a high-resolution text mode differ from those 
reported when it is started from an 80x25 text mode. 

8ciocks— For the PVG A1 chi pset, the default is 4 clocks 
Somecardswith thischipset may support 8 clocks. Specifying 
thisoption will allow the driver to detect and usetheextra 
clocks 

isciocks— ForTrident tvga8900b and 8900c chipsets. Some 
newer boards using 8900B and 8900c chipsets actually support 
16 clocks rather than the standard 8 clocks. Such boards will 
haveaTCK9002 oncK9004 chip on them. Specifying thisoption 
will allow the driver to detect and use the extra 8 clocks. 
probe_ciocks— For C irruschipsets. T he C irrus driver has a 
fixed set of clocks that are normally used. Specifying this 
option will force the driver to probe for clocks instead of 
reporting the built-in defaults. Thisoption is for debugging 
purposes only. 

powen_saver— Thisoption enables the server to use the power¬ 
saving features of VESA D PM S-compatible monitors. T he 
suspend level iscurrently not supported. Refer to the 
xF86Conf±g (4/5) manual page for details of how to setthetime- 
outs for the different levels of operation. T his option is 
experimental. 

noaccei— For C irrus and W D chipsets. Thisoption disables 
the accelerated features for the cigd5426, cigd5428, wd90c24, 
wd90c3i, and wd90c33 chipsets. 

fifo_conservative— For C irrus chipsets. Thisoption sets the 
crt_fifo threshold to a conservative value for dot clocks above 
65M FI z. This reduces performance, but may help in 
eliminating problemswith "streaks” on thescreen during 
BitBu operations. 

tifo_aggressive— For C irrus chipsets. This option sets the 
crt_fifo threshold to an aggressive value for dot clocks above 
65M FI z. T his may increase performance. 
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siow_dram— For C irrus chi psets. This option sets the D RAM 
timings for slow DRAM chips. 

fast_dram — For ET 4000 and Cirrus chipsets. Thisoption sets 
the DRAM timingsfor fast D RAM chips 
no_ 2 mb_banksei — For C irrus chi psets. This option is required 
for Cirrus cards with 2MB of videoram, which is in the form of 
512kx8 D RAM s (4 chips) rather than 256kx4 D RAM s (16 
chips). 

nojutbit— For Cirrus chi psets. Thisoption disables use of 
hardware BitBLT. 

linear— Attempt a linear mapping of the framebuffer into 
high memory. C urrently only supported for some C irrus 
configurations. 

med_dram, favour_bitblt, sw_cursor, clgd6225_lcd, mmio— M Ore 
C irrus-specific options. Refer to /usr/xiiR6/iib/xii/doc/ 
readme. cirrus for a detai led description of Cirrus options, 
speedup 11 s e i e c t i on " Sets the selection of speedups to use. The optional selection 

string can takethefollowing values: 
none 
all 

If the selection string is omitted, or if the speedup option is 
omitted, the selection defaults to ail. Someof theSpeedU ps 
can only be used with theET4000, WD90C31, and WD90C33 
chipsets and others require a virtual resolution with axdim of 
1024. SpeedUps that won't work with agiven configuration 
are automatically disabled. 

D i sables theSpeedU p code. This is equivalent to speedup 

none. 

This specifies the type of RAM DAC used on the board. Only 
the ark driver currently uses this. RAM DAC types recognized 
include 

Att2Oc490— AT&T 20C490 or compatible 8-bit RAM DAC. 
Att20c498— AT&T 20C498 or compatible 16-bit RAM DAC. 
zoomdac— RAM DAC used by the FI ercules Stingray Pro/V and 
64/V. 

stgi700— STG1700 or compatible RAM DAC. 

N otethat xFree86 has some internal capabilities to determine what hardware it is running on. Thus, normally the keywords 
chipset, clocks, and videoram don't haveto be specified. But there may be occasionswhen this autodetection mechanism 
fails, (for example, too high a load on the machine when you start the server). For cases I ike this, you should first run 
xf86_svga on an unloaded machine; look at the results of the autodetection (that are printed out during server startup), and 
then explicitly specify these parameters in the configuration file It is recommended that all parameters, especially clock 
values, be specified in thexF86Config file. 

FILES 

<XRoot>/bin/XF86 SVGA 
/etc/XF86Config 
<XRoot>/lib/X11/XF86Config 
<XRoot>/lib/X11/doc/README.ark 
<XRoot>/lib/X11/doc/README.ati 


The SVG A color X server 

Server configuration file 

Server configuration file 

Extra documentation for the ARK driver 

Extra documentation for the AT I vgawon-der driver 


nospeedup 
Ramdac ramdac-type 
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<XRoot>/lib/XI1/doc/README.cirrus 
<XRoot>/lib/X11/doc/README.trident 
<XRoot>/lib/X11/doc/README.tseng 
<XRoot>/lib/X11/doc/README.Oak 
<XR00t>/lib/X11/doc/README.Video7 
<XRoot>/lib/X11/doc/README.WstDig 

Note: <xRoot> refers to theroot oftheXll install tree. 


Extra documentation for the C i rrus driver 

Extra documentation for theTrident driver 

Extra documentation for the ET 4000 and ET 3000 drivers 

Extra documentation for the Oak driver 

Extra documentation for the Video7 driver 

Extra documentation for theWD/PVGA driver 


SEE ALSO 

x(l), Xserver(l), XFree86(l), XF86Config(4/5), xf86config(l), xvidtune(l), xdm(l), xinit(l) 

BUGS 

Bug reports are welcome, and should be e-mailed to the address listed below. 

CONTACT INFO 

xFreese source isavailablefrom the FT P serverftp.xFree86.org. 

Send e-mail to xFree86@xFree86.org for details. 

AUTHORS 

Refer to thexFree86(l) manual page. 

xFree86 Verson 3.1.2 


XF86_VGA16 

xf86 vgai6 — 4-bit nonaccelerated X W indow System server for UNIX on x86 platforms 

SYNOPSIS 

XF86 VGA16 [:displaynumber] [ option ] ... 

DESCRIPTION 

xf86j/gai6 is a 4-bit color server forvGA cards. The default root visual for this server isstaticcoior. It also includes support 
for the non-VGA monochrome cards described in thexF86_Mono(l) manual page. It may be run in a dual-headed configura¬ 
tion. 

CONFIGURATIONS 

The xf86_vgai 6 server supports the foil owing popular svga chipsets in 16-color mode. 

ATI 18800, 18800-1, 28800-2, 28800-4, 28800-5, 28800-6, 68800-3, 

68800-6, 68800AX, 68800LX, 88800CX, 88800GX 

T seng ET 4000 

Trident TVGA8800CS, TVGA8900B, TVGA8900C, TVGA8900CL, TVGA9000 

Cirrus CL 6410 , CL 6412 , CL 6420 , CL 6440 

Oak OTI067, OTI077, OTI087 

Additionally, it supports generic VGA cards. 

xf86_vgai6 does not support the accelerated functions of the supported chipsets. 
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OPTIONS 

In addition to the normal server options described in thexserver(l) manual page, xf86_vgai6 accepts some more command- 
lineswitches, as described in thexFree86(l) man page. 

SETUP 

xFree86 uses a configuration file called xF86Contig for its initial setup. 

SeethexF86Config(4/5) man page for general details. Here, only thexF86_vGAi6 specific parts are explained. 

TheDriver entry in the screen section of thexFseconfig file should be set to vgai6.T o run in dual-headed configuration, 
there should also be a screen section with the Driver entry set to mono. 

Entries for theDevice section in thexFseconfig fi le include the followi ng: 

Specifies a chipset so the correct driver can be used. Possible 
chipsets are 

ATI vgawonder 

T Seng et4000, et4000w32, et4000w32i, et4000w32p 

Trident tvga8800cs, tvga8900b, tvga8900c, 

tvga8900cl, tvga9000 

Cirrus C16410, C16412, C16420, C16440 

Oak oti067, oti077, oti087 

Generic VGA generic 

Allows the user to select certain optionsprovided by the 
drivers. Currently, the following strings are recognized: 
legend— For Sigma Legend ET4000-based boards. This option 
enables a special clock-selection algorithm used on Legend 
boards, and M UST be specified for these boards to function 
correctly. 

hibit iow, hibit_high— For Tseng ET 4000 chipsets. W ith some 
ET 4000 cards, the server has difficulty getting the state of the 
high-order clocks select bit right when started from a high- 
resolution text mode. T hese options allow the correct initial 
state of that bit to be specified. To find out what the correct 
initial state is, start the server from an 80x25 text mode. This 
option is only needed if the clocks reported by the server when 
started from a high-resolution text mode differ from those 
reported when it is started from an 80x25 text mode. 
powen_saver— This option enables the server to use the power 
savi ng features of V E SA D P M S-compati bl e mon i tors. T he 
suspend level is currently not supported. 

Refer to the xF86Contig(4/5) manual page for details of how to 
set the time-outs for the different levels of operation. This 
option is experimental. 

N otethat xFree86 has some internal capabilities to determine what hardware it is running on. Thus normally the keywords 
chipset, clocks, and videoram don't have to be specified. But there may be occasionswhen this autodetection mechanism 
fails, (for example, too high a load on the machine when you start the server). For cases I ike this, you should first run xf86 
vgai6 on an unloaded machine, look at the results of the autodetection (that are printed out during server startup), and then 
explicitly specify these parameters in the configuration file. It is recommended that all parameters, especially clock values, be 
specified in thexF86Config file. 


chipset "name" 


Option “opti onst ri ng" 
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FILES 

<xRoot>/bin/xF86 vgai6 Thel6-colorX server 

/etc/xF86Contig Server configuration file 

<xRoot>/iib/xi i /xF86Conf ig Server configuration file 

Note: <xRoot> refers to the root oftheXll install tree. 

SEE ALSO 

x(l), Xserver(l), XFree86(l), XF86Config(4/5), XF86 Mono(l), xf86config(l), xvidtune(l), xdm(l), xinit(l) 

CONTACT INFO 

xFreese source isavailablefrom the FT P serverftp.xFree86.org. 

Send e-mail to xFree86@xFree86.org for details. 

AUTHORS 

Theprimary developer of this server isGertjan Akkerman (akkerman@dutiba.twi.tudeift.nl). 

See also the xFree86(l) manual page. 

xFree86 Version 3.1.2 
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xf86config— Generate an xF86Contig file 

SYNOPSIS 

xf86config 

DESCRIPTION 

xf86config is an interactive program for generating an xFseconfigfiie for use with xFree86 X servers. 

FILES 

<xroot>/iib/xn/cards Video cards database 

SEE ALSO 

XFree86(l), XF86Conf ig(4/5), reconfig(l) 

AUTHOR 

H arm H anemaayer 

xFree86 Version 3.1.1 
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xfd — D isplay all the characters in anX font 

SYNOPSIS 

xfd [-options ...] -fn font name 
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DESCRIPTION 

Thexfd utility creates a wi ndow containing the name of the font being displayed, a row of command buttons, several lines of 
text for displaying character metrics, and a grid containing one glyph per cell. The characters are shown in increasing order 
from left to right, top to bottom. The first character displayed at the top left will be character number 0 unless the -start 
option has been supplied, in which case the character with the number given in the -start option will be used. 

The characters are displayed in agrid of boxes, each large enough to hold any single character in the font. Each character 
glyph isdrawn using the PoiyTexti6 requestfused bythexiib routine xDrawstringi6). I f the-box option isgiven, arectangle 
will bedrawn around each character, showing where an imageTextie request (used bythexiib routinexDrawimagestringi6) 
would cause background color to be displayed. 

The origin of each glyph is normally set so that the character isdrawn in the upper left corner of the grid cell. H owever, if a 
glyph has a negative left bearing or an unusually large ascent, descent, or right bearing (as is the case with cursor font), some 
characters may not appear in their own grid cells. The -center option may be used to force all glyphs to be centered in their 
respective cells 

All the characters in the font may not fit in the window at once. T o seethe next page of glyphs, press the N ext button at the 
top of the window. T o seethe previous page, press Pra/. T o exit xtd, press Quit. 

Individual character metrics (index, width, bearings, ascent, and descent) can bedisplayed at thetop of thewindow by 
clicking on the desired character. 

The font name displayed at thetop of thewindow isthefull name of the font, as determined by theserver. Seexisfonts for 
ways to generate lists of fonts, as well as more detailed summaries of their metrics and properties. 


OPTIONS 


xtd accepts all of the standard toolkit command-line options along with the following additional options 


-fn font 

-box 

-center 

-start number 

-be color 

-rows numrows 

-columns numcol s 


This option specifies the font to bedisplayed. This can also be 
set with the FontGrid font resource. A font must be specified. 
This option indicates that a box should bedisplayed outlining 
the area that would be filled with background color by an 
imageText request. T his can also be set with the FontGrid 
boxchars resource. T he default isFaise. 

This option indicates that each glyph should be centered in its 
grid. Thiscan also be set with the FontGrid centerchars 
resource. The default is False. 

This option specifies the glyph index of the upper left corner 
of the grid. This is used to view characters at arbitrary 
locationsin the font. Thiscan also beset with theFontG rid 
startchar resource. The default iso. 

Thisoption specifies the color to beused if imageText boxes 
aredrawn. Thiscan also be set with theFontG rid boxcoior 
resource. 

Thisoption specifies the number of rows in the grid. Thiscan 
also be set with the FontGrid ceiiRows resource 
Thisoption specifies the number of columns in the grid. This 
can also beset with theFontG rid ceiicoiumns resource. 


WIDGETS 

In order to specify resources, it is useful to know the widgets that compose xtd. In the notation below, indentation indicates 
hierarchical structure. The widget class name is given first, followed by the widget instance name. The application class name 
iSXfd. 
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Xfd xfd 

Paned pane 

Label fontname 
Box box 

Command quit 
Command prev 
Command next 
Label select 
Label metrics 
Label range 
Label start 

Form form 
FontGrid grid 


FONTGRID RESOURCES 

The FontGrid widget is an application-specific widget, and a subclass of the Simple widget in the Athena widget set. The 
effects and instance names of this widget's resources are given in the "Options" subsection. Capitalize the first letter of the 
resource instance name to get the correspondi ng class name. 


APPLICATION SPECIFIC RESOURCES 


The instance names of the application-specific resources are given in thefollowing list. Capitalizethefirst letter of the 
resource instance name to get the corresponding class name. These resources are unlikely to be i nteresti ng unless you are 
localizing xfd for a different language. 


selectFormat 


metricsFormat 


rangeFormat 


startFormat 


nocharFormat 


Specifies a printf-style format string used to display informa¬ 
tion about the selected character. The default is character 
0 x% 02 x% 02 x (%u,%u) (%#o,%#o). T he arguments that will come 
after the format string are 

char.bytel, char.byte2, char.bytel, char.byte2, char.bytel, 
char.byte 2 . char.bytel is byte 1 of the selected character. 
char.byte 2 isbyte 2 of the selected character. 

Specifies a printf -style format string used to display character 
metrics. T he default iSwidth %d; left %d, right %d; ascent 
%d, descent %d (font %d, %d). T he arguments that will come 
aftertheformatstringarethecharactermetricswidth, 

Ibearing, rbearing, character ascent, character descent, font 
ascent, and font descent. 

Specifies a printf -style format string used to display the range 
of characters currently being displayed. T he default is range: 
0 x% 02 x% 02 x (%u,%u) thru 0 x% 02 x% 02 x <%u,%u) .Thearguments 
th at w i 11 come after the format string are the followi ng fields 
from thexFontstruct that is returned from opening the font: 
min_byte1, min_char_or_byte2, min_byte1 ( min_char_or_byte2, 
max_byte1, max_char_or_byte2, max_byte1, max_char_on_byte2. 
Specifies a printf -style format string used to display informa¬ 
tion about the character at the upper left corner of the font 
grid. The default is upper left: 0x%04x (%d ,%d ). T he 
arguments that will come after theformat string are the new 
character, the high byte of the new character, and the low byte 
of the new character. 

Specifies a printf-style format string to display when the 
selected character does not exist. The default is no such 
character 0 x% 02 x% 02 x (%u,%u) (%#o,%#o. T he arguments that 
will come after theformat string are the same as for the 
select-Format resource. 
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SEE ALSO 

x(l), xisfonts(l), xrdb(l), xfontsei(l), X Logical Font Description Conventions 

BUGS 

The program should skip over pages full of nonexistent characters. 

AUTHOR 

Jim Fulton (M IT X Consortium); previous program of the same name by M ark Li Mi bridge (M IT Project Athena) 

X Verson 11 Releas6 
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XFree86— X11R6 for U N IX on x86 platforms 

DESCRIPTION 

xFreese is a collection of X servers for U N IX-likeOSson Intel x86 platforms. This work is derived from X386ni . 2 , which was 

contributed to xhrs by Snitily Graphics Consulting Service. 

CONFIGURATIONS 

xFree86 operates under the following operating systems: 

■ SVR3.2: SCO 3.2.2, 3.2.4, ISC 3.x, 4.x 

■ SVR4.0: ESIX, M icroport, D ell, U H C, C onsensys, M ST, I SC, AT &T, N C R 

■ SVR4.2: Consensys, Univel (UN IXWare) 

■ Solaris (x86) 2.1, 2.4 

■ FreeBSD 1.1.5, 2.0, 2.0.5, N etBSD 1.0 (i386 port only) 

■ BSD/386 version 1.1 and BSD/OS 2.0 

■ M ach (from C M U) 

■ Linux 

■ Amoeba version 5.1 

■ M inix-386vm version 1.6.25.1 

■ LynxOS AT versions2.2.1 and 2.3 

NETWORK CONNECTIONS 

xFree86 supports connections made usi ng the following reliable byte-streams: 

Local xFnee86 supports local connectionsviaStreamspipevia various 

mechanisms, using thefollowing paths(n represents the 
display number): 

/dev/X/server.n (SVR3 and SVR4) 

/dev/X/Nserver.n (SVR4) 

/dev/XnS and /dev/XnR (SCO SVR3) 

In SVR4.0.4, if the Advanced Compatibility Packageis 
installed, and in SVR4.2, xFree86 supports local connections 
from clients for SCO XSight/O D T, and (with modifications 
to thebinary) clients for ISC SVR3. 

UNIX Domain xFree86 uses /tmp/.xn -unix/xn as the filename for the socket, 

where n isthe display number. 
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TCPIP xFree86 listens on port htons( 6000 +n), where n isthedisplay 

number. 

Amoeba RPC This is the default communication medium used under native 

Amoeba. Note that under Amoeba, the server should be 
started with ahostname: di spi aynumber argument. 


ENVIRONMENT VARIABLES 

For operating systems that support local connections other than UNIX Domain sockets (SVR3 and SVR4), there is a 
compiled-in list specifying the order in which local connections should be attempted. T his list can be overridden by the 
xlocal environment variable described next. If the display name indicates a best-choice connection should be made (for 
example, 10 . 0 ), each connection mechanism istried until aconnection succeeds or no more mechanismsare available. Note: 
For these OSs, theU NIX Domain socket connection is treated differently from the other local connection types. To use it 
theconnection must bemadeto unix: 0 . 0 . 

The xlocal environment variable should contain a list of one more of the following: 

NAMED 

PTS 

SCO 

ISC 


which represent SVR4 Named Streams pipe, 0 Id-style U SL Streams pipe, SCO X Sight Streams pipe, and ISC Streams pipe, 
respectively. You can select a single mechanism (for example, xlocal=named), or an ordered list, for example, 

XL0CAL=" NAMED: PTS: SCO" 

This variable overrides the compiled-in defaults. For SVR4 it is recommended that named be the first preference connection. 
The default setting is 

PTS:NAMED:ISC:SCO. 

T 0 globally override thecompiled-in defaults, you should define (and export if using sh or ksh) xlocal globally. If you use 
startx/xinit, the definition should beat the top of your .xinitrc file. If you usexdm, the definitions should be early on in 

the <XRoot>/lib/X1 1 /xdm/Xsession Script. 


OPTIONS 


In addition to the normal server options described in thexserver(l) manual page, xFree86 accepts the foil owing command¬ 
line switches: 


vtXX 

-probeonly 

-quiet 
-bpp n 

-weight nnn 

-gamma value 


xx specifiestheVirtual Terminal device number that xFreess 
will use. Without thisoption, xFree86 will pick the first 
availableVirtual Terminal that it can locate. Thisoption 
applies only to SVR3, SVR4, Linux, and BSD OSs with the 
syscons or pcvt driver. 

C auses the server to exit after the device probing stage. T he 
xF86Config file isstill used when thisoption isgiven, so 
information that can be auto detected should be commented 
out. 

Suppresses most informational messages at startup. 

Set number of bits per pixel. The default is 8. Legal values are 
8,15,16, 24, 32. N ot all servers support all values. 

Sets RGB weighting at 16 bpp. The default is 565. This applies 
only to those servers that support 16 bpp. 

Sets the gamma correction, value must be between 0.1 and 10. 
The default is 1 . 0 . This value is applied equally to the R, G, 
and B values. N ot all servers support this. 
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-rgamma value 

-ggamma value 

-bgamma value 

-showconfig 

-verbose 

-xf86config file 

-keeptty 

KEYBOARD 

M ultiple key presses recognized directly by xFree86 are 
C trl+Alt+Backspace 

C trl+Alt-i-K eypad-Plus 
Ctrl+Alt+Keypad-M inus 
Ctrl-HAit+F 1... F12 


Sets the red gamma correction, value must be between 0.1 and 
10. The default is i . 0 . Not all servers support this. 

Sets the green gamma correction, value must be between 0.1 
and 10. The default is i . 0 . N ot all servers support this. 

Sets the blue gamma correction, value must be between 0.1 
and 10. The default is 1 . 0 . N ot all servers support this. 

Prints out a list of screen drivers configured in theserver. 

M aximizes information printed at startup (morethan the 
default). 

Reads the server configuration from file. T his option is only 
available when theserver is run as root (that is, with real- 
UID 0). 

Prevents the server from detaching its initial controlling 
terminal.Thisoption isonly useful when debuggingthe 
server. 


Immediately kills the server— no questions asked. (Can be 
disabled by specifying "Dontzap" in theServer-Flags section of 
the XF86Config file) 

Changes video mode to next one specified in theconfiguration 
file, (increasing video resolution order). 

Changes video mode to previous one specified in the 
configuration file, (decreasing video resolution order). 

For BSD systems using thesysconsdriver and Linux, these 
keystroke combinations are used to switch to Virtual Console 
1 through 12. 


SETUP 

xFreese uses a configuration file called xF86Contig for its initial setup. Refer to the xF86Conf ig(4/5) manual page for more 
information. 


FILES 

<XRoot>/bin/XF86 SVGA 
<XRoot>/bin/XF86 Mono 
<XRoot>/bin/XF86 S3 
<XRoot>/bin/XF86 Mach8 
<XRoot>/bin/XF86 Mach32 
<XRoot>/bin/XF86 Mach64 
<XRoot>/bin/XF86 P9000 
<XRoot>/bin/XF86 AGX 
<XRoot>/bin/XF86 W32 
<XRoot>/bin/XF86 8514 
/etc/XF86Config 

<XRoot>/lib/X11/XF86Config.hostname 
<XRoot>/lib/X11/XF86Config 
<XRoot>/bin/ 


The color SVG A X server 

ThemonochromeX server for VGA and other mono cards 

The accelerated S3 X server 

T he accelerated Machs X server 

T he accelerated Mach32 X server 

T he accelerated Mach64 X server 

The accelerated P 9000 X server 

The accelerated agx X server 

The accelerated ET 4000 /W 32 X server 

T he accelerated 8514 /A X server 

Server configuration file 

Server configuration file 

Server configuration file 

Client binaries 



xFree86 


<XRoot>/include/ 

<XRoot>/lib/ 

<XRoot>/lib/X11/fonts/ 

<XRoot>/lib/X11/rgb.txt 
<XRoot>/lib/X11/XErrorDB 
<XRoot>/lib/X11/app-defaults/ 

<XRoot>/man/man?/ 

/etc/Xn.hosts 

N ote: <xRoot> refers to the root of the X11 install tree. 


H eader files 

Libraries 

Fonts 

Color namesto RGB mapping 
C lient error message database 
Client resource specifications 
M anual pages 

Initial access control list for display n 


SEE ALSO 

X(l), Xserver(l), xdm(l), xinit(l), XF86Config(4/5), xf86config(l), XF86 SVGA(l), XF86 VGA16(1), XF86 Mono(l), XF86 Accel(l), 
xvidtune(l) 


AUTHORS 

For xi iR5, xf86 1.2 was provided by the following: 

ThomasRoell (roell®infonmatik.tu-muenchen.de; Server and SVR4 stuff), M ark W . Snitily (mark9sgcs.com sgcs; SVR3 
support, X Consortium Sponsor), and many more people out there on theN et who helped with ideas and bugfixes. 

xFree86 was integrated into xi iR6 by the following team: 

Stuart Anderson (anderson9metroiink.com), Doug Anson (danson9igc.com), G ertjan Akkerman 

(akkerman9dutiba.twi.tudelft.nl), M ike BemSOn (mike9mbsun.mlb.org), Robin C Utshaw (robin9XFree86.org), D avid D 3W6S 
(dawes9XFree86.org), M arc E vans (marc9XFree86. org), Pascal H aible (haible9izfm. uni -Stuttgart .de), M atthieu H errb 
(Matthieu.Herrb91aas.fr), D irk H Ohndel (hohndel9XFree86.org), D avid FI Olland (davidh9use.com), Alan FI Ourihane 
(alanh9fairlite.demon.co.uk), J effrey FI SU (hsu9soda.berkeley.edu), G lenn Lai (glenn9cs.utexas.edu), Ted Lemon 
(mellon9ncd.com), Rich M urphey (rich9XFree86.org), FH anSN asten (nasten9everyware.se), M ark Snitily (mark9sgcs.com), 
Randy Terbush (randyt9cse.unl.edu), J On TOmbS (tombs9XFree86.org), Kees Verstoep (versto9cs. vu. nl), Paul Vixie 
(paul9vix.com), M ark W eaver (Mark Weaver9brown.edu), D avid W exelblat (dwex9XFree86.org), Philip W heatley 
(Philip.Wheatley9ColumbiaSC.NCR.COM), T homas W Olfram (wolf9prz.tu-berlin.de), and 0 rest Zborowski 
(orestz9eskimo.com). 


T he xFree86 enhancement package was provided by 
David Dawes, dawes9XFree86.org 

Glenn Lai, glenn9cs.utexas.edu 

J im T Si 11 as, jtsilla9ccs.neu.edu 
David Wexelblat, dwex9XFree86.org 


D irk FI Ohndel, hohndel9XFree86.org 

AmanciO FI astyjr., hasty9netcom.com 
Rich M urphey, rich9XFree86.org 


Release coordination, administration of FTP repository and 
mailing lists. Source tree management and integration, 
accelerated server integration, fixing, and coding. 

TheSpeedU p codefor ET 4000 -based SVGA cards, and ET4000/ 
W 32 accelerated server. 

M any server speedupsfrom thefX386 series of enhancements. 
Integration of thefX386 code into the default server, many 
driver fixes, and driver documentation, assembly of theVGA 
card/monitor database, development of the generic video 
mode listing. Accelerated server integration, fixing, and 
coding. 

Linux-shared libraries and release coordination. Accelerated 
server integration and fixing. Generic administrivia and 
documentation. 

Porting to 386BSD version 0.1 and XS3 development. 

Ported to 386BSD version 0.1 based on theoriginal port by 
PaceWillison. Support for 386BSD, FreeBSD, and N etBSD. 
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Robert Baron, Robert . Baron@ernst.mach.cs.emu.edu 

0 rest Z borowski, orestz@eskimo. com 

Doug Anson, danson@lgc.com 

D avid H Olland, davidh@use.com 

D avid M cC ullough, davidm@stallion.oz.au 

M ichael Rohleder, michael.rohleder@stadt-frankfurt.de 

Kees Verstoep, versto@cs.vu.ni 

M arc Evans, Marc@XFree86.org 

Philip H omburg, phiiip@os.vu.m 

T homas M ueller, tm@systrix.de 

Jon TOmbS, tombs@XFree86.org 

H arald Koenig, koenig@tat.physik.uni-tuebingen.de 

Bernhard Bender, br@elsa.mhs.compuserve.com 

Kevin M artin, martin@cs.unc.edu 

Rik Faith, faith@cs.unc.edu 
Tiago Gons, tiago@comosjn.hobby.nl 
HansNasten, nasten@everyware.se 

MikeBemSOn, mike@mbsun.mlb.org 

M ark W eaver, Mark Weaver@brown.edu 

C raig G roeschel, craig@metrolink.com 

H enry W Orth, Henry.Worth@amail.amdahl. com 

Erik N ygren, nygren@mit.edu 

H arry Langenbacher, harry@brain. jpl.nasa.gov 

ChrisM ason, mason@mail.csh.rit.edu 

H enrik H armsen, harmsen@eritel.se 

Simon Cooper, scooper@vizlab.rutgers.edu 

Harm Hanemaayer, hhanemaa@cs.ruu.m 

M i ke T i emey, f loyd@eng .umd.edu 

Bill Conn, conn@bnr.ca 

Brad Bosch, brad@lachman.com 

Alan H ourihane, alanh@fairlite.demon.co.uk 

M arc La France, Marc.La-France@ualberta.ca 

Steve G Oldman, sgoldman@encore.com Oak 

J Orge D elgado, ernar@dit.upm.es 

Bill Conn, conn@bnr.ca 

Paolo Severini, lendl@dist.dist.unige.it 

Ching-Tai Chiu, cchiu@netcom.com 

M anfred Brands, mb@oceonics.m 

Randy H endry, randy@sgi.com 

Frank D ikker, dikker@cs.utwente.nl 

Regis C ridlig, cridlig@dmi.ens.fr 

Jon Block, block@frc.com 


Ported to M ach. 

Ported to Linux. 

Ported to Solaris x86. 

Ported to Solaris x86. 

Ported to SCO SVR3. 

Ported to ISC SVR3. 

Ported to Amoeba based on Leendert van Doorn'soriginal 
Amoeba port of X11R5. 

Ported to OSF/1. 

Ported to M inix-386vm. 

Ported to LynxOS. 

S3 server and accelerated server coordination. 

S3 server development. 

S3 server development. 

Overall work on the base accelerated servers (AT I and 8514/ 
A), and M ach64 server. 

Overall work on the base accelerated servers (ATI and 8514/A). 
M ach8 and 8514/A server development. 

M ach8, 8514/A, and S3 server development and BSD/386 
support. 

M ach32 server development. 

M ach32 server development. 

M ach32 server development. 

AGX server. 

P9000 server. 

P9000 server. 

P9000 server. 

P9000 server. 

Cirrus accelerated code (based on work by Bill Reynolds). 
Cirrus accelerated code and ARK driver. 

WD accelerated code. 

WD accelerated code. 

WD 90C24A support. 

Trident SVGA driver 
ATI vgawonder SVGA driver 
067/077 SVGA driver. 

Oak SVGA driver, and 087 accelerated code. 

WD accelerated code. 

AL2101 SVGA driver. 

Avance Logic ALI SVGA driver. 

Cirrus64xxSVGA driver. 

Cirrus6440 support in thecl64xxSVGA driver. 

MX SVGA driver. 

C hips & Technology driver. 

C hips & Technology driver. 
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M ike H Ollick, hollick@graphics.cis.upenn.edu 

PeterT rattler, peter@sbox.tu-graz.ac.at 

Craig Struble cstruble@acm.vt.edu 

Gertjan Akkerman, akkerman@dutiba.twi.tudelft.nl 

D avor M atic, dmatic@Athena.MIT.EDU 

Pascal Haible, haible@izfm.uni-stuttgart.de 


C hips & T echnology driver 
RealTek SVGA driver. 

Video7 SVGA driver. 

16-color VGA server, and X F86C onfig parser. 

H ercules driver. 

Banked monochromeVGA support, H ercules support, and 
mono frame buffer support for dumb monochrome devices, 
and many more people out there on theN et who helped with beta-testing this enhancement. 
xFree86 source is avail able from the FT P server ftp.xFree86.org, among others. Send e-mail to xFree86@xFree86.org for 
details. 

xFree86 Verson 3.1.2 
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xfs— X font server 


SYNOPSIS 

xfs [-config confi gurati on_fiI e] [-port tcp port ] 


DESCRIPTION 

xfsistheX Window System font server. It supplies fonts to X Window System display servers. 

STARTING THE SERVER 

The server is usually run by a system administrator, and started via boot files like /etc/re. local. Users may also wish to start 
private font servers for specific sets of fonts. 


OPTIONS 

-config conf iguration_fiie Specifies the configuration file the font server will use. 

-is listen-socket Specifies a file descriptor that is already set up to beused asthe 

listen socket. Thisoption isonly intended to beused by the 
font server itself when automatically spawning another copy of 
itself to handle additional connections. 

-port tcp_port Specifies theT CP port number on which the server will listen 

for connections. 


SIGNALS 

SIGTERM 

SIGUSR1 

SIGUSR2 

SIGHUP 


This causes the font server to exit cleanly. 

T his signal isused to cause the server to reread its configura¬ 
tion file 

This signal isused to cause the server to flush any cached data 
it may have. 

This signal isused to cause the server to reset, closing all active 
connections and rereading the configuration file. 
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CONFIGURATION 


The configuration language is a list of keyword and value pairs. Each keyword is followed by an = and then the desired value. 


Recognized keywords include the foil owing: 
catalogue (list Of String) 


alternate-servers (list Of String) 
client-limit (cardinal) 

clone-self (Boolean) 
default-point-size 

(cardinal) 

default-resolutions 

(list of resolutions) 


error-file (String) 

port (cardinal) 
use-sysiog (Boolean) 

deferglyphs (string) 


Ordered list of font path element names. Use of the key-word 
"catalogue" is very misleading at present; the current 
implementation only supports a single catalogue (ail), 
containing all of the specified fonts 
List of alternate servers for thisfont server. 

N umber of clients thisfont server will support before refusing 
service. T his is useful for tuning the load on each individual 
font server. 

W hether thisfont server should attempt to clone itself when it 
reaches theciient-iimit. 

T he default pointsize (in decipoints) for 
fonts that don't specify. The default is 120 . 

Resolutions the server supports by default. 

This information may be used as a hint for 
prerendering, and substituted for scaled fonts that do not 
specify a resolution. A resolution isacomma- 
separated pair of x and y resolutions in pixels 
per inch. M ultipie resolutions are separated by commas. 
Filenameof theerror file. All warnings and errors will be 
logged here. 

TCP port on which the server will listen for connections. 
Whether sysiog(3) (on supported systems) isto be used for 
errors 

Set the mode for delayed fetching and caching of glyphs. Value 
isnone, meaning deferred glyphs is disabled, an, meaning it is 
enabled for all fonts and ie, meaning it isenabled only for 16- 
bits fonts. 


EXAMPLE 

# 

# sample font server configuration file 

# 

# allow a max of 10 clients to connect to this font server client-limit = 10 

# when a font server reaches its limit, start up a new one clone-self = on 

# alternate font servers for clients to use alternate-servers = hansen:7101,hansen:7102 

# where to look for fonts 

# the first is a set of Speedo outlines, the second is a set of 

# misc bitmaps and the last is a set of 100dpi bitmaps 

# 

catalogue = /usr/X11R6/lib/X11/fonts/speedo, 

/usr/XI1R6/lib/XI1/fonts/misc, 

/usr/X11R6/lib/X11/fonts/100dpi/ 

# in 12 points, decipoints 
default-point-size = 120 

# 100 x 100 and 75 x 75 
default-resolutions = 100,100,75,75 
use-syslog = off 
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FONT SERVER NAMES 

0 ne of the following forms can be used to name a font server that accepts T C P connections 

tcp/hos t name: port tcp/host name: por t /cat a I oguel i s t 

The host name specifies the name (or decimal numeric address) of the machine on which the font server is running. Theport 
is the decimal TCP port on which the font server is listening for connections. Thee at a i oguel i st specifies a list of catalogue 
names, with + as a separator. 

Examples: tcp/fs.x.org:7100, tep/18.30.0.212:7101/ all. 

One of the following forms can be used to name a font server that accepts D EC net connections 
decnet/nodena me: :font$obj name decnet/n ode name: :font$obj name /cat a I oguel i st 

The no den a me specifies the name (or decimal numeric address) of the machine on which the font server is running. The 
obj name is a normal, case-in sensitive D EC net object name. Thecat a i oguel i st specifies a list of catalogue names, with + as a 
separator. 

Examples: DECnet/SRVNOD: :FONT$DEFAULT, decnet/44.70: :font$special/symbols. 

SEE ALSO 

x(l), font server implementation overview 

BUGS 

M ultiple catalogues should be supported. 

AUTHORS 

DaveLemkefN etwork Computing Devices, Inc.), Keith Packard (M assachusetts Institute of Technology) 

X Version 11 Release 6 


xhost 

xhost— Server access control program for X 

SYNOPSIS 

xhost [[+-]name ...] 

DESCRIPTION 

The xhost program is used to add and delete hostnames or usernames to the list allowed to make connections to theX server. 
In the case of hosts, this provides a rudimentary form of privacy control and security. It is only sufficient for a workstation 
(singleuser) environment, although it does limit the worst abuses. Environments that requiremore sophisticated measures 
should implement the user-based mechanism or use the hooks in the protocol for passing other authentication data to the 
server. 

OPTIONS 

xhost accepts the foil owing command-line options. For security, the options that effect access control may only be run from 
the "control ling host." For workstations this is the same machine as the server. ForX terminals, it is the login host. 

-help Prints a usage message. 

[+] n a me T he given aa me (the plus sign is optional) is added to the list 

allowed to connect to theX server. The name can be a 
hostname or a username. 
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-na me 

The given name is removed from the list allowed to connect to 
the server. The name can be a hostname or a username. 
Existing connections are not broken, but new connection 
attempts will be denied. Note that the current machine is 
allowed to be removed; however, further connections 
(including attempts to add it back) will not be permitted. 
Resetting the server (thereby breaking all connections) isthe 
only way to allow local connectionsagain. 

+ 

Access is granted to everyone, even if they aren't on the list (in 
other words, access control isturned off). 

- 

Access is restricted to only those on the list (that is, access 
control isturned on). 

not hi ng 

If no command-line arguments are given, a message i ndicati ng 
whether or not access control is currently enabled is pri nted, 
followed by the list of those allowed to connect. Thisisthe 
only option that may be used from machines other than the 
controlling host. 

NAMES 

A complete name has thesyntaxf ami i y 

: n a me where th e f am i 1 i es are as f o 11 ows: 

inet 

Internet host 

dne 

DEC net host 

nis 

Secure RPC network name 

krb 

KerberosV5 principal 

local 

C ontains only one name, the empty string 


The family is case insensitive. The format of the name varies with the family. 

When Secure RPC is being used, the network-independent netname (for example, nis:unix.uid@domainname) can be 
specified, or a local user can be specified with just the username and a trailing at sign (@) (for example, nis:pat@). 

For backward compatibility with pre-R6 xhost, names that contain an at sign are assumed to be in thenis family. Otherwise, 
the inet family is assumed. 

DIAGNOSTICS 

For each nameadded to the access control list, a line of the form name being added to access control list isprinted. For 
each nameremoved from the access control list, a line of the form name being removed from access control list isprinted. 

FILES 

/etc/X*.hosts 

SEE ALSO 

X(l), Xsecurity(l), Xserver(l), xdm(l) 

ENVIRONMENT 

display T o get the default host and display to use 

BUGS 

You can't specify a display on the command line because -display is a valid command-line argument (indicating that you 
want to remove the machine named display from the access list). 
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TheX server stores network addresses, not hostnames. This is not really a bug. If somehow you changea host's network 
address while the server is still running, xhost must be used to add the new address and/or remove the old address. 

AUTHORS 

Bob Scheifler (M IT Laboratory for Computer Science) andjim G ettys (M IT Project Athena/D EC) 

X Verson 11 Re/ease 6 
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xieperf— XIE server extension test and demo program 

SYNTAX 

xieperf [-option ...] 

DESCRIPTION 

The xieperf program is based upon rs xiiperf(l) , and while not entirely comprehensive in its coverage of the xie protocol 
(seethe "Bugs" subsection), it is intended to be useful in the evaluation of xie implementations in the areas of protocol 
adherence and performance. The xieperf program includes tests that execute each of the protocol requests and photoflo 
elements specified by revision 5.0 of the xie protocol. In addition, xieperf provides a set of tests that can be used to validate 
the detection and transmission of xie protocol request errors, such asFloM atch, FloValue, and so forth. Finally, xieperf 
provides a customizable demonstration program for xie. 

A test ismadeup of three components executed in sequence: an initialization function, a test function, and an end function. 
The initialization function is responsible for allocating and populating test resources, such as photo maps and LUT s, and for 
creating a stored photoflo that will be executed by the test function. The test function, in most cases, simply executes the 
stored photoflo for a specified number of repetitions. The end function, which is cal led following the test function, is used 
primarily to destroy any noncacheable server resources used by the test, and to free any memory that was dynamically 
allocated by theclient. Sometests, such as -modifyi, -await, -abort, and -redefine, perform additional steps within the test 
function innerloop, as required bytheelement being tested, or in an attempt to make the test more visually appealing. 

Evaluating the performance of individual xie elements is not as simple as measuring CoreX drawing times. The xie protocol 
requires elements to be embedded within photoflosin order to be exercised, and the minimum possible photoflo size is two. 
This implies that it is impossible to measure performance of a single element in isolation—the time it takes to run theflo 
depends on what other elements exist in theflo. Extrapolating performance of a single element (or technique) in aflo must 
be done carefully, on a case-by-case basis, becausein general, measured element performance depends on input image size, 
datatype, and other factors all of which can be influenced by upstream flo elements. N ote further that the number and type 
of elementsin aflo can beinfluenced by the visuals availableon thedisplay, so even flo-flo comparisonson machines with 
different visuals must bedonewith caution. 

M anytest labels contain an abbreviated pipeline description. Forinstance, ip/il/p/ed indicates importPhotomap, importuu, 
Point, and ExportDrawabie. Pipelinesending in ed (ExportDrawabie) often includehidden elements such asBandExtract, 
convertToindex, Dither, or Point to match theflo output to the screen visual. Pipelines ending in ep (ExportPhotomap) will 
result in a blank window. 

xieperf is compatible with xiiperfcomp(l), which is used to compare the outputs of different xieperf andxiiperf runsin a 
nice tabular format. In xieperf you will need to use the - labels option (see the "Options" subsection), and provide the 
resulting labelsfileto xiiperfcomp(l) to obtain correct output. Seethexiiperfcomp(l) man pages for moredetailson this. 
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OPTIONS 

xiepertacceptsthefollowingoptions: 
-display host:dpy 
-images <p a t h > 


-timeout<s > 


-sync 

-script <f i I e > 


-repeat <n> 


-time <s > 

-depth <de pt h > 

-Grayscale 

-Pseudocolor 

-StaticGray 

-StaticColor 

-TrueColor 

-DirectColor 

-WMSafe 


Specifies which display to use. 

N ormally, xiepert references image files located in the 
directory images, which xiepert assumes is located in your 
current directory. If the images directory is not in your current 
directory, orthefilehasbeen renamed, use this option to 
specify its location. 

Sometests require the reception of an event such asFioNotity 
to continue, and may cause xieperf to hang should these 
events not be received. This option allowstheuserto specify a 
time-out value which, if exceeded, will cause xiepert to give 
up waiting for an event, and continue on with the next test in 
sequence. Should an a/ent time-out, a warning message will be 
printed to stdem. The default time-out value is 60 seconds. 
Runs the tests in synchronous mode. 

Using this option gives the user the ability to run asubset of 
the available tests and control the number of times the tests are 
executed on an individual basis. This is thought to be 
especially useful for those running xiepert for demonstration 
purposes. Using this option causes xiepert to read commands 
specified in a script file, or from stdin if <file>\s -. T estsare 
specified by newline-terminated input linesof theform 
command [-reps n ] [ -repeat m ]. C haracteTS followi ng and 
including# are treated as comments. Seethe -mkscript option. 
Repeats each test n times (by default each test is run two 
times). Thisoption may be used in script files also, in which 
case the script file -repeat overrides the command-line option. 
Specifies how long in seconds each test should be run (default 
5 seconds). 

Use a visual with <depth> planes per pixel (default isthe 
default visual). 

Use a Grayscale visual (default is the default visual). 

U se a Pseudocolor visual (default is the default vi sual). 

Use a StaticGray visual (default is the default visual). 

Use a staticcoior visual (default is the default visual). 

U se a TrueColor visual (default is the default visual). 

Use a DirectColor visual (default is the default visual). 

If xiepert must be run in a window manager environment, use 
thisflagto make xiepert aware of this. If specified, xiepert 
will create a window, identical to the size of the root window, 
and all further windows created by xiepert will be transient 
pop-up children of thiswindow. If thisflag is omitted, xiepert 
will set the override redirect attribute Of all windows to True 
and will also do evil things such as calling xinstaiicoiormap. 
Using thisoption will cause the window manager to (hope¬ 
fully) obey window geometry hints specified by xiepert. 
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-showtechs 


-showlabels 


-showevents 


-events 

-errors 

-loCal 


-all 


-tests 


-mkscript 


-cache <n> 


-labels 


-DIS 


-range <t est 1>[ ,<t est 2>] 


D isplay a comprehensive list of techniques, by category, 
indicating which of the techniques are supported by thexiE 
server. 

Print test label to screen prior to calli ng any of the test code. 
This allows the user to know which test is executing in case the 
test hangs for some reason. 

Be verbose when running a/ent and error tests. Also, can be 
used to catch and display information on any signals received 
during execution of xieperf. N ote that this flag is best used in 
a debugging situation, or to validate that the error events 
recei ved by xieperf are val i d the fi rst ti me the tests are 
executed on a new platform. 

Run tests that test for event generation. 

Run tests that test for error event generation. 

Skip test calibration. This may be used when running xieperf 
in situations where execution timing is not important. 
Execution times will not be reported by xieperf when this 
option is enabled. T he inner loop repeat count, additionally, is 
set to a value of 5 (but can be overridden by the -reps option). 
Runs all tests. This may take a while; depending on the speed 
of your machine, and its floating-point capabilities. This 
option isignored if a script file is used. 

G enerate a list of the available tests for the xieperf program. 

In xiiperf, this list is normally displayed in theusage 
statement. It was yanked from the usage of xieperf because it 
wastoo lengthy. 

G enerate a script fi le suitable for use with the script option. If 
-repeat or -reps are also specified, they will be automatically 
placed attheend of each command in the script. The script is 
generated to stderr. Seethe -script command, above. 

M ost test flos utilize a photomap resource for a source. A 
photomap cacheof up to n entries is controlled by xieperf to 
avoid having to constantly reload these images during test 
initialization. The default cache size is 4 . If a value less than the 
default is specified, thecache size will beset to the default. 
Generates just the descriptive labels for each test specified. U se 
-ail or -range to specify which tests are included. See 
xiiperfcomp(l) for more details 

Pretend we are running xieperf while connected to a Dis-only 
capableimplementation of xie. T hiswiII cause xieperf to 
execute those tests that only use protocol requests found in the 
dis subset of xie, and bypass those which arenotDis- 
compatible If xieperf detects a dis server, it will do this 
automatically, and this option isignored. Use -an or - range to 
specify the initial range of tests. 

Runs all the tests starting from the specified nametesti until 
thenametesG, including both the specified tests. Some tests, 
like the a/ent and error tests, also require the - errors or - 
events optionsto specified. T his option isignored if a script is 
used. 
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-reps <n> Fix the inner loop repetitions to n . T his indicates how many 

times the photoflo will be executed each time the test is run. 
This option is overridden on a per test basis if specified in a 
script. Typically, xiepert determinesthe ideal number of reps 
during each test's calibration period. 

-importobscuredEvent Test generation of events. Requires -events flag, 

through -ExportAvailable 


-Badvaiue through T est generation of errors. Requires -errors flag. 

-FloValueError 


-ColorList 

-LUT 

-Photonap 

-ROI 

-Photospace 

-Photoflo 

-QueryPhotomap 

-QueryColorList 

-QueryTechniquesDefault 

through -QueryTechniques 

WhiteAdjust 

-QueryPhotoflo 

-PurgeColorList 

-Abort 


-Await 


-importclientlutl 
-importclientphotol through 
-importclientphoto9 

-importclientroil 
-importclientroi2 
-encodephotol through 
-encodephoto14 


C reate anddestroy colonist resource test. 
C reate and destroy lut resource test. 

C reate and destroy Photomap resource test. 

C reate and destroy roi resource test. 

C reate and destroy Photospace test. 

C reate and destroy Photoflo test. 
QueryPhotomap resource test. 

Query colonist resource test. 

Q uery techniques as specified by test name. 


Query Photoflo test. 

Purge colonist test. 

This test creates a photoflo that is started and blocks for data 
provided by Putciientoatao. Instead of sending the data, the 
test usesxieAborto to stop the photoflo, and then waits for 
the PhotofioDone event to be sent by the server. If the test times 
out waiting for the event, an error message is sent to stderr. 

T his test creates a flo of theform importciientiuT -> 

ExportLUT, and startstheflo executing, xieperf then forks, and 
thechild process streamstheLUT data to theflo using 
PutciientData, while the parent blocks in xieAwait. If theflo 
successfully finishes, xieAwait will return and theflo state, after 
query, will indicate that it has completed. If xieAwait does not 
complete naturally, or after return from xieAwait theflo is still 
active, an error is reported to stderr. N ote, on a really slow 
machine, it is possible that xieAwait will return before theflo 
has a chance to finish. In this case, use the - timeout option to 
increase the time-out for this test. 

ImportClientlUT -> ExportLUT test. 

Flos Of the form ImportClient-Photo -> ExportPhotomap using 
various decode techniques, for example, G32D, tiff2 , 
UncompressedTriple. 
importciientRoi with 10 rectangles. 
importciientRoi with 100 rectangles. 

Flos Of the form ImportPhotomap - ExportPhotomap using 
various encode techniques, for example G32D, tiff2 , 
UncompressedTriple. 0riginal encoding isshown in left 
window; image after encoding isshown in rightwindow. 
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-encodeclientphotol through 
-encodeclientphotol 1 


-exportclientlutl 

-exportclientroil 


-exportclientroi2 

-exportclienthistograml 

through 

-exportclienthistogram4 

-exportclienthistogramroil 

through 

-exportclienthistogramroi4 

-exportclienthistogramcplanel 

through 

-exportclienthistogranicplane4 

-importlutl 

-importphotol 

-importphoto2 

-importroil 

-importroi2 

-importdrawablel 

-importdrawable2 

-importdrawable3 

-importdrawable4 

-importdrawable5 

-importdrawable6 

-importdrawable7 

-importdrawable8 

-constrainl 


T WO fl OS, oneof theform ImportPhotomap ■> 
ExportciientPhoto, and the other of the form 
ImportClientPhoto -> ExportPhotomap, where 
ExportciientPhoto in the fi rst flo uses various encode 
techniques, for exam pie G32D, tiff2 , uncompressedTripie. The 
image before encoding isdisplayed in the left window, while 
the right window shows the image that was encoded in the 
first flo and read back in the second flo. 

ExportciientLUT test. LUT is displayed in a histogram window. 
ExportciientRoi test, 10 RO Is. T he ROI sthat are sent to the 
server are represented by the filled rectangles. T he RO I s that 
are received back from the server by the client are drawn as 
white-bordered, nonfilled rectangles. T he resulting output 
illustrates how the server combined the rectangles sent to it. 
Same as exportclientroil, except using 100 rectangles. 
Exportciient Histogram tests using various images. The 
histogram isdisplayed in awindow that overlaps theimage. 

Same as the ExportciientHistogram test, but usi ng a RO I 
to identify the area of interest. 


Same as the ExportciientHistogram test, but usi ng a 
control planeto identify the area of interest. 

Test importLUT element; LUT size is256. 

ImportPhotomap -> ExportPhotomap, with Source and destina¬ 
tion equal. 

ImportPhotomap -> ExportDrawable, window destination. 
importRoi -> ExportRoi, 10 rectangles, source and desti nation 
RO I s equal. 

importRoi -> ExportRoi, 100 rectangles, source and destination 
RO I s equal. 

ImportDrawable -> ExportDrawable, source is pixmap, 
destination is window. 

ImportDrawable -> ExportDrawable, Source and destination are 
both window. 

ImportDrawable -> ExportDrawable, destination window 
obscured by source window. 

ImportDrawable -> ExportDrawable, SOUrcewindOW Obscured 
by destination window. 

ImportDrawablePlane -> ExportDrawablePlane, pixmap, source 
= desti nation. 

ImportDrawablePlane -> ExportDrawablePlane, wi ndOW, Source 
= desti nation. 

ImportDrawablePlane -> ExportDrawablePlane, wi ndOW, Source 
obscures destination. 

ImportDrawablePlane -> ExportDrawablePlane, wi ndOW, 

destination obscures source 

Constrain Hardciip technique test, drawable desti nation. 
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-constrain2 

-constrainphotol 

-constrainphoto2 

-convolvel 

-convolve2 

-convolve3 

-convolve4 

-convolveroil 

-convolveroi2 

-convolvecplanel 

-convolvecplane2 

-mathl through -mathcplane7 

-arithmeticdyadicl through 
-arithmeticdyadic5 
-arithmeticmonadicl through 
-arithmeticmonadic9 
-arithmeticdyadicroil 
through 

arithmeticdyadicroi5 

-arithmeticmonadicroil 

through 

-arithmeticmonadicroi9 

-arithmeticdyadiccplanel 

through 

-arithmeticdyadiccplane5 

-arithmeticmonadiccplanel 

through 

-arithmeticmonadiccplane9 

-arithmeticfloatdyadicl 

though 

-arithmeticfloatdyadic5 

-arithmeticfloatmonadicl 

though 

-arithmeticfloatmonadic9 

-arithmeticroifloatdyadicl 

to 

-arithmeticroifloatdyadic5 

-arithmeticroifloatmonadicl 

to 

-rithmeticroifloatmonadic9 

-bandl 


Constrain ciipscaie technique test, drawable destination. 
Constrain Hardciip technique test, photomap destination. 
Constrain ciipscaie technique test, photomap destination. 
Boxcar 3x3 convolution test. Smoothing or lowpassfilter. 
Boxcar 5x5 convolution test. Smoothing or lowpass filter. 
LaPlacian 3x3 convolution test. Edge or high pass filter. 
LaPlacian 5x5 convolution test. Edge or high pass filter. 
LaPlacian 3x3 convolution test, with ROI. 

LaPlacian 5x5 convolution test, with ROI. 

LaPlacian 3x3 convolution test, with control plane. 

LaPlacian 5x5 convolution test, with control plane. 

Various tests that exercise themath element, some tests using 
ROI sand control planes. 

Arithmetic element tests, using photomaps 
as the operands. 

Arithmetic element tests, photomap and constant operands. 

Arithmetic element tests, using - photomaps as the 
operands, with RO Is. 

Arithmetic element tests, photomap and 
constant operands, with RO Is. 

Arithmetic element tests, usi ng photomaps as the 
operands, with control planes. 

Arithmetic element tests, photomap and constant 
operands, with control planes. 

Arithmetic element tests, using photomaps 
as the operands, unconstrained. 

Arithmetic element tests, photomap and constant 
operands, unconstrained. 

Arithmetic element tests, photomaps as the 
operands, rois, unconstrained. 

Arithmetic element tests, photomap and 
constant operands, ROIs, unconstrained. 

Bandseiect element test. Image input istriple band. If visual of 
xiepert window is a color visual, then three Band-select 
elements are used to extract the individual bands; the/ are 
combined once again using Bandcombine, and displayed using 
convertToindex. If the visual is not color, for example 
Grayscale or staticGray, then theflo simply uses one 
Bandseiect element to extract a single band for display. 
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-band2 

Bandcombine test. Input bands are made of three separate single 
band photomaps. These are combined using a Bandcombine 
element, which is followed by aBandExtract and 
ExportDrawable. CCIR 601-1 coefficients. 

-band3 

BandExtract test. Input is a triple band photomap. CCIR 

601-1 coefficients. Destination window colormap is gray ramp. 

-band4 

BandExtract test. Input is a triple band photomap. CCIR 

601-1 coefficients. Destination window colormap is rgb best 
map standard colormap. 

-band5 

BandExtract test. Input is a triple band photomap. CCIR 

601-1 coefficients. Destination window colormap is 
rgb_default_map standard colormap. 

-comparedyadicl through 

T est various compare operators with dyadic 

-comparedyadic6 

photomap operands. 

-comparemonadicl through 

T est various compare operators with photomap, 

-comparemonadic6 

constant operands. 

-compareroidyadicl through 

Test various compare operatorswith dyadic photomap 

-compareroidyadic6 

operands, using ROIs. 

-compareroimonadicl through 

T est various operators with photomap, 

compare compareroimonadic6 

constant operands, using RO Is. 

-comparecplanedyadicl 

Test various compare operatorswith dyadic 

through 

-comparecplanedyadic6 

photomap operands, control planes. 

-comparecplanemonadicl 

Test various compare operatorswith photomap, 

through 

-comparecplanemonadic6 

constant operands, control planes. 

-matchhistograml 

MatchHistogram element tests, using various 

through 

-matchhistogram18 

images and histogram matching techniques. 

-matchhistogramroil 

A selection of MatchHistogram element 

through 

-matchhistogramroi6 

tests, with ROIs 

-matchhistogramcplanel 

A selection of M atchH istogram element 

through 

-matchhistogramcplane6 

tests, with control planes. 

-unconstrainl 

ImportPhotomap, Unconstrain, Constrain(ClipScale), 
ExportDrawable test. 

-pasteupl through -pasteup2 

Pasteup element tests. 

-geometryl through 

Geometry element tests, including rotations, scales, 

-geometryH 

and mirroring. NearestNeighbor technique. 

-geometry15 through 

Geometry element tests, including rotations, scales, 

-geometry28 

and mirroring. AntiAiias technique. 

-geometry29 through 

Geometry element tests, including rotations, scales, 

-geometry42 

and mirroring. Biiinearinterpoiation technique. 

-geomg31dscale1 through 

T eststo exercise the various FAX decoders and 

-geometryfaxradiol 

the Geometry element. 

-ditherl 

Dither test, ErrorDiffusion dither technique, ExportDrawable. 

-dither2 

Dither test, ErrorDiffusion dither technique, 
ExportDrawablePlane. 
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652 

-dither3 

-dither4 

-dithers 

-dither6 

-dither7 

-dither8 

-logicalmonadicl through 
-logicalmonadic16 
-logicaldyadicl through 
-logicaldyadic16 
-logicalmonadicroil through 
-logicalmonadicroil6 
-logicaldyadicroil through 
-logicaldyadicroil6 
-logicalmonadiccplanel 
through 

-logicalmonadiccplanel6 

-logicaldyadiccplanel 

through 

-logicaldyadiccplanel6 
-blendl 

-blend2 

-blendroil 

-blendroi2 

-blendcplanel 

-blendcplane2 

-blendalphal 

-blendalpha2 

-blendalpharoil 

-blendalpharoi2 

-triplepointl through 
-triplepoint2 
-funnyencodel through 
-funnyencode8 


Dither test, Ordered (4) dither technique, ExportDrawable. 

Dither test, Ordered (4) dither technique, ExportDrawablePlane. 
Dither test, 0 rdered(8) dither technique, ExportDrawable. 

Dither test, 0 rdered(8) dither technique, ExportDrawablePlane. 
Dither test, D efault dither technique, ExportDrawable. 

Dither test, D efault dither technique, ExportDrawablePlane. 
Logical element, photomap and a constant 
of 0 as operands, various operators. 

Logical element tests, dyadic photomaps as 
operands, various operators. 

Logical element, photomap and constant of 
0 operands, various operators, RO Is. 

Logical element, dyadic photomaps as operands, various 
operators, RO Is. 

Logical element, photomap and constant of 0 
operands, various operators, Control Planes. 

Logical element, dyadic photomaps as operands, 
various operators, control planes. 

Biend element test. M onadic source, 0.1 source constant. 

Alpha constant of 0.5. 

Biend element test. D yadic sources. Alpha constant of 0.5. 

Biend test. M onadic source, 0.1 source constant. Alpha 
constant of 0.5. ROIs 

Biend element test. D yadic sources. Alpha constant of 0.5. 

Uses ROIs. 

Biend test. M onadic source, 0.1 source constant. Alpha 
constant of 0.5. control plane. 

Biend element test. D yadic sources. Alpha constant of 0.5. 
control plane. 

Biend test. M onadic source, 220 source constant. Alpha plane 
is a photomap. 

Biend test. D yadic sources. Alpha plane is a constant 220. 

Biend test. M onadic source, 220 source constant. Alpha plane 
photomap. ROIs. 

Biend test. D yadic sources. Alpha plane is a constant 220. 

ROIs 

Illustrate use of point and standard colormaps 
for rendering triple band images. 

These tests are designed to perform limited exercising of X IE's 
capability of dealing with various encodings of flo source data. 
Thetest init function obtains a photomap using icp ■> ep.A 
series of independent permanent flo pairs oneof theform ip 
-> ep, and the other of the basic form ip -> ed, are con¬ 
structed. T he encodi ng parameters for the ExportPhotomap (ep) 
element in the first flo are derived from test configuration. The 
number of flo pairscreated isalso dependent upon test 
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-pointl through -point3 

-pointroil 

-pointcplanel 

-pointphotol 

-pointroiphotol 

-pointcplanephotol 

-redefine 


-modifyl 

-modify2 

-modify3 

-modify4 


-modify5 


-rgbl through -rgb 16 


-converttoindexpixel 

-converttoindexplane 


configuration. The tests can beconfigured so that the test init 
function will constrain the input photomap to a specified 
number of levels, on a per band basis, so that word-si zed and 
quad-sized pixels are passed through theflos. Some tests below 
take advantage of this. See tests.c for test configuration, and 
hintson how to add similar tests. 

Simple Point element tests. D rawable destination. 

Simple Point element test that uses ROI s. D rawable destination. 
Simple Point element test that uses a control plane. D rawable 
destination. 

Simple Point element test. Photomap destination. 

Simple Point element test that uses RO Is. Photomap 
destination. 

Simple Point element test that uses a control plane. Photomap 
destination. 

T wo flographs are created that are the same in structure, 
except for the x and y offsets specified for the ExportDrawabie 
flo elements. The test init function creates a photoflo based 
upon one of the two flographs. T he inner loop of the test 
function usesxieRedefinePhotofio() to alternate between each 
of the flographs. M ake sure that your inner loop reps are 2 or 
greater in order to exercise this test fully (see -reps). 

Test xieModityPhotofioo by adjusting RO I offsets and size. 
Test xieModifyPhotofiod by changing the LUT input to a 
Point element. 

T est xieModifyPhotofiod by changi ng ExportDrawabie x and y 
offsets. 

T his test creates a rather long flo of arithmetic elements, each 
of which does nothing more than add i to a small image. The 
test mit function scalesthe input photomap. T he 
ExportDrawabie x and y offset is modified randomly during 
each iteration of the test function inner loop. 

This test creates a rather long flo of arithmetic elements, each 
of which does nothing more than add i to a large image. Each 
rep, the Geometry and ExportDrawabie elements at the end of 
the flo are modified to crop a small piece of the input into its 
appropriate place in the larger image. 

These tests all basically take an uncompressedTripie image as 
input, send it to convertFromRGB, which converts the image to 
some configured colorspace, and then send the converted 
image on to convertToRGB priorto display. T he origi nal image 
isdisplayed in the left-hand window, and theimagethat has 
passed through theflo isshown in theright-hand window. 
Thegoal of these test isto show that convertFromRGB -> 
ConvertToRGB islOSSleSS. 

ConvertToIndex test, TripleBand BandByPixel. 

ConvertToIndex test, TripleBand BandByPlane. 
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-convertfromindex 


-complex 

X DEFAULTS 

There are no X defaults used by this program. 

SEE ALSO 

X(l), xllperf(l), xllperfcomp(l) 

BUGS 

There should bean images environment variable to augment the -images option. 

M any tests only scratch thesurfaceof possi bletest cases. Some of the options available for certain flo elements are either 
inadequately tested, or ignored altogether. There are insufficient tests for bitonal, large pixel, or tripleband tests. 

Some of the test names are inconsistently cased, for example, -Abort and -ditheri. 

Sometests are hopelessly slow when run against machineswith slow FPUs 

Bitonal images are, for the most part, displayed using the ExportDrawabie flo element; however, ExportDrawabiePiane would 
be a better choice. 

AUTHOR 

Syd Logan (AGE Logic, Inc.) 

X Verson 11 Release 6 


Thetest init function uses a flo containing convertToindex to 
display an imagein the left window. Thetest function uses 
thisdrawableas input to a flo that does corwertFromindex -> 
convertToindex and sends the resulting image to theright 
window. The result should be lossless. 

A somewhat large flo that uses control planes, LUTs, Point, 
PasteUp, Logical, Constrain, Dither, Geometry, MatchHistogram, 
Bandcombine, and Bandseiect elements. See the Postscript file 
compiex.ps for a rendition of thephotoflo that is executed. 


ximtoppm 

ximtoppm— Convert an xim file into a portable pixmap 

SYNOPSIS 

ximtoppm [ x i mf i I e ] 

DESCRIPTION 

Reads an xim file as input. Produces a portable pixmap as output. The xim toolkit is included in thecontrib tree of the 
X.V11R4 release. 

SEE ALSO 

ppm(5) 

AUTHOR 

Copyright (c) 1991 byjef Poskanzer. 


25 March 1990 
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xinetd 

xinetd— The extended Internet services daemon 

SYNOPSIS 

xinetd [options] 

DESCRIPTION 

xinetd performs the same function asinetd: it starts programs that provide Internet services. Instead of having such servers 
started at system initialization time and be dormant until a connection request arrives, xinetd is the only daemon process 
started and it listens on all service ports for the services listed in its configuration file. When a request comes in, xinetd starts 
the appropriate server. Because of the way it operates, xinetd (as well asinetd) is also referred to as a super-server. 

The services listed in xinetd's configuration file can be separated into two groups. Services in the first group are called 
multithreaded and they require the forking of a new server process for each new connection request. The new server then 
handles that connection. For such services, xinetd keeps listening for new requests so that it can spawn new servers. On the 
other hand, the second group includes services for which the service daemon is responsible for handling all new connection 
requests. Such services are cal led single-threaded and xinetd will stop handling new requests for them until the server dies. 
Services in this group are usually datagram based. 

So far, the only reason for the existence of a super-server was to conserve system resources by avoiding to fork a lot of 
processes who might be dormant for most of their lifetime. W hi le fulfil ling this function, xinetd takes advantage of the idea 
of a super-server to provide features such as access control and logging. Furthermore, xinetd is not limited to services listed in 
/etc/services. T herefore, anybody can use xinetd to start special-purpose servers. 

OPTIONS 

-d Enables debug mode. T his produces a lot of debugging 

output, and it makes it possible to use a debugger on xinetd. 
-sysiog sysi og_faci i i ty This option enables sysiog logging of xinetd-produced 

messages using the specified sysiog facility. The following 
facility names are supported: daemon, auth, user, iocai[0-7] 
(check sysiog. cont (5) for their meanings). T his option is 
ineffective in debug mode because all relevant messages are 
sent to the terminal. 

-fiieiog logfiie xinetd-produced messageswill beplaced in thespecifiedfile 

M essages are always appended to the file If the file does not 
exist, itwill be created. This option is ineffective in debug 
mode because all relevant messages are sent to the terminal. 

D etermi nes the fi le that xinetd uses for confi guration. The 
default is /etc/xinetd.conf. 

Theprocesspid is written to standard error. Thisopti on is 
ineffective in debug mode. 

This option sets the loop rate beyond which a service is 
considered in error and is deactivated. The loop rate is 
specified in terms of the number of servers per second that can 
be forked for a process. The speed of your machine determines 
the correct value for this option. The default rate is 10 . 

If thisoption isused, xinetd will setthesocket option 
so_reuseaddr before binding the service socket to an Internet 
address. T his allows binding of the address even if there are 
programs that use it, which happenswhen a previous instance 
of xinetd has started some servers that are still running. This 
option has no effect on RPC services. 


-f config_file 
-pid 

-loop rate 

-reuse 
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This option places a limit on the number of concurrently 
running processes that can be started by xinetd. Its purpose is 
to prevent processtable overflows. 

This option places a limit on the number of concurrently 
runningserversforremoteuserlDacquisition. 

This option places a limit on the number of concurrently 
running servers for service shutdown (forked when the record 
option is used). 

T he sysiog and fiieiog options are mutually exclusive. If none is specified, the default issysiog using the daemon facility. 
You should not confuse xinetd messages with messages related to service logging. The latter are logged only if this is specified 
viatheconfiguration file. 

CONFIGURATION FILE 

The configuration file determines the services provided by xinetd. Any line whose first nonwhitespace character is a# is 
considered a comment line. Empty lines are ignored. 

The file contains entries of the form: 

service <service_name> 

{ 

<attribute> <assign_op><value><value> ... 

} 

The assignment operator, assign_op, can be one of =, +=, -=. The majority of attributes support only the simple assignment 
operator, =. Attributes whose value is a set of values support all assignment operators. For such attributes, += means adding a 
value to the set and -= means removing a value from the set. A list of these attributes is given after all the attributes are 
described. 

Each entry defines a service identified by the service_name. The following is a list of available attributes: 

id This attribute is used to uniquely identify a service. This is 

useful because there exist services that can use different 
protocolsand need to be described with different entries in the 
configuration file. By default, theserviceid isthesameasthe 
servi cename. 

type Possible values are the following: 

rpc If this is an rpc service 

internal If this is a service provided by xinetd. 

unlisted If this is a service not listed in /etc/services, 

flags Possible flag values are 

reuse Set the so_reuseaddr flag on the service socket. 

intercept Intercept packets or accepted connectionsin 
order to verify that they are coming from 
acceptable locations (internal or multithreaded 
services cannot be intercepted). 
noretry Avoid retry attempts in case of fork failure, 

socket type Possible values are 

stream Stream-based service 

dgram D atagram-based service 

raw Servi ce that requi res di rect access to IP 

seqpacket Servi ce that requi res rel i able sequenti al 
datagram transmission 


-limit p r o c _ I i mi t 

-logprocs I i mi t 
-shutdownprocs I i mi t 
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protocol 


wait 


user 


group 


instances 


server 

server_args 


only_from 


no_access 


Determines the protocol that is employed by the service. The 
protocol mustexistin /etc/protocois. I f this attribute is not 
defined, the default protocol employed by the service will be 
used. 

This attribute determines if the service issingle- threaded or 
multithreaded. If its value is yes, the service is single-threaded; 
this means that xinetd will start the server and then it will stop 
handling requests for the service until the server dies. If the 
attribute value is no, the service is multithreaded and xinetd 
will keep handling new service requests. 

D etermi nes the uid for the server process. The username must 
exist in /etc/passwd. T his attribute is ineffective if the effective 
user ID of xinetd is not super-user. 

D etermi nes the gid for the server process. The group name 
must exist in /etc/group. If a group is not specified, the group 
of user will beused (from /etc/passwd). T his attribute is 
ineffective if the effective user ID of xinetd is not super-user. 

D etermi nes the number of servers that can be si multaneously 
active for a service. By default, there is no limit. The value of 
this attri bute can be either a number or unlimited, which 
means that there is no limit. 

D etermi nes the program to execute for th i s servi ce. 

Determines the arguments passed to the server. In contrast to 
inetd, the server name should not be included in server_args. 

D eterm i n es th e rem ote h osts to wh i ch th e parti cu I ar servi ce i s 
available. Its value is a list of IP addresses that can be specified 
in any combination of thefollowingways: 

a) A numeric address in theform of %d.%d.%d.%d. If the 
rightmost components area, they are treated as wildcards 
(for example, 128 . 138 . 12.0 matches all hosts on the 
I28.i38.i2 subnet). 0 . 0 . 0.0 matches all Internet addresses. 

b) A factorized address in the form of %d .%d ,%d ,{%d ,%d,...}. 
There is no need for all four components 

(%d ,%d .{%d ,%d,.. .%d } is also OK). H owa/er, the factorized 
part must be at the end of the address. 

c) A network name (from /etc/networks). 

d) A hostname. All IP addresses of the specified hostnamewill 
beused. 

Specifying this attri bute without a value makes the service 
available to nobody. 

D eterm i n es th e rem ote h osts to wh i ch th e parti cu I ar servi ce i s 
unavailable. Its value can be specified in the same way as the 
value of theonly from attribute. These two attributes 
determine the location access control enforced by xinetd. If 
none of the two is specified foraservice the service is avail able 
to anyone. If both are specified foraservice, the one that is the 
better match for the address of the remote host determi nes if 
the service is avail able to that host (for example if theonly 
from list contains 128 .138.209.0 and the no access list contains 
I28.i38.209.i0, then the host with the address 128 . 138 . 209.10 
can not access the service). 
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access times 


log_type 


log_on_success 


log_o n _failure 



Determines the time intervals when the service is available. An 
interval hastheform hour: mi n-hour: mi n (connectionswill be 
accepted at the bounds of an interval). H ours can range from 0 
to 23 and minutes from 0 to 59. 

D etermi nes where the service log output is sent. T here are two 
formats: 

SYSLOG syslog T he log output is sent to syslog at 
facility the specified facility. If a level 

[syslog level] is present, the messages will be recorded at 
that level instead of log_info (which isthe 
default I e/el). 

file file The log output is appended to f i i e , 

[soft iimit which will be created if it does 
[hard_iimit] ] not exist. T wo limits on the size of the log 
file can be optionally specified. The first 
limit isasoft one; xinetd will log a message 
the first time this li mit isexceeded (if xinetd 
logs to syslog, the message will be sent at 
the log_alert priority level). The second 
limit isa hard limit; xinetd will stop logging 
for the affected service (if the I og file is a 
common log file then more than one service 
may be affected) and will log a message 
about this (if xinetd logsto syslog, the 
message will be sent at the log alert priority 
level). If a hard limit is not specified, it 
defaults to the soft limit increased by 1 
percent but the extra size must be within the 
parameters log_extra_min and log_extra_max 
(defined in config.h). 

Determines what information is logged when a server is started 
and when that server exits (the service ID is always included in 
the log entry). Any combination of the following values may 
be specified: 

pid Logstheserver process ID. (If the service is 

implemented by xinetd without forking another 
process, the logged process ID will beo.) 
host Logs the remote host address 

time Logsthetimewhen the server was started. 

userid Logs the user ID of the remote user using the 
RFC 931 identification protocol. Thisoption is 
available only for multithreaded stream services. 
exit Logs the fact that a server exited along with the 

exit status or the termination signal (the process 
ID is also logged if the pid option is used). 
duration Logs the duration of a service session. 
Determines what information is logged when a server cannot 
be started (either because of a lack of resources or because of 
access control restrictions). The service ID is always included 
in the log entry along with the reason for failure. Any 
combination of thefollowing values may be specified: 

host Logs the remote host address. 
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rpc_version 


env 


passenv 

port 


time Logsthetimewhen the server was started. 

userid LogstheuserID oftheremoteuserusingtheRFC 

931 identification protocol. Thisoption is available 
only for multithreaded stream services. 
attempt Logs the fact that afailed attempt wasmade. 
record Records information from the remote end in case 
theserver could not be started. This allows 
monitoring of attempts to use the service. For 
example, thelogin service logs the local user, 
remote user, and terminal type Currently, the 
services that support this option areiogiun, shell, 
exec, finger. 

Determines the RPC version for an RPC service. The version 
can bea single number or a range in theform number- 
number. 

The value of this attribute is a list of strings of theform 
name=vaiue. These strings will be added to the environment 
before starting a server (therefore the server's environment will 
include xinetd s environment plus the specified strings). 

T he value of this attribute is a list of environment variables 
from xinetd's environment that will be passed to theserver. 

D etermi nes the servi ce port. I f th is attri bute is sped fi ed for a 
service listed in /etc/services, it must be equal to the port 
number listed in that file. 


You don't need to specify all of the preceding attributes for each service. The necessary attributes for a service are the 


following: 


socket type 


user 

(non-unlisted services only) 

server 

(non-internal services only) 

wait 


protocol 

(RPC and unlisted services only) 

rpc_version 

(RPC services only) 

port 

(unlisted services only) 


The following attributes support all assignment operators, except as indicated: 

only_from 

no_access 

log_on_success 

log_on_failure 

passenv 

env (does not support the -= operator) 

These attributes can also appear more than once in a service entry. The remaining attributes support only the = operator and 
can appear at most once in a service entry. 

T he configuration file may also contain a single defaults entry that has the form: 

defaults 

{ 

<attribute> = <value><value> ... 
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T his entry provides default attri bute values for service entries that don't specify those attri butes. Possible default attri butes: 
logotype 
log_on_success 
log_on_failure 
only_from 
no_access 
passenv 
instances 

disabled (cumulative effect) 

Attri butes with a cumulative effect can be specified multi pie times with the values specified each time accumulating (in other 
words, = does the same thing as +=). With the exception of disabled they all have the same meaning as if they were specified 
in a service entry, disabled determines services that are disabled even if they have entries in the configuration file This allows 
for quick reconfiguration by specifying disabled services with the disabled attribute instead of commenting them out. The 
value of this attribute is a list of space-separated service IDs. 

INTERNAL SERVICES 

xinetd provides the following services internally (both stream- and datagram-based): echo, time, daytime, chargen, and 
discard. T hese services are under the same access restricti ons as all other services except for the ones that don't require xinetd 
to fork another process for them. Those ones (time, daytime, and the datagram-based echo, chargen, and discard) have no 
limitation in thenumber of instances. 

CONTROLLING xinetd 

xinetd performs certain actions when it receives certain signals. The actions associated with the specific signals can be 
redefined by editing contig.h and recompiling. 

Causes a soft reconfiguration, which meansthat xinetd rereads 
the configuration file and adjusts accordingly. 

Causes a hard reconfiguration, which is the same as a soft 
reconfiguration except that servers for services that are no 
longer available are terminated. Access control isperformed 
again on running servers by checking the remote location, 
access times and server instances. If the number of server 
instances is lowered, some arbitrarily picked servers will be 
killed to satisfy the limit; thiswill happen after any servers are 
terminated because of failing the remote location or access 
time checks. Also, if the intercept flag was clear and is set, any 
running servers for that service will determinated; the purpose 
of this is to ensure that after a hard reconfiguration there will 
be no running servers that can accept packets from addresses 
that do not meet the access control criteria. 

C auses program termination. 

T ermi nates all running servers before terminating xinetd. 
Causes an internal state dump (the default dump file is /tmp/ 
xinetd.dump; to change the filename, edit contig.h and 
recompile). 

Causes an internal consistency check to verify that the data 
structures used by the program have not been corrupted. 

When the check is completed xinetd will generate a message 
that says if the check was successful or not. 


SIGUSR1 

SIGUSR2 


SIGQUIT 

SIGTERM 

SIGHUP 

SIGIOT 


(cumulative effect) 
(cumulative effect) 
(cumulative effect) 
(cumulative effect) 
(cumulative effect) 
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On reconfiguration, the log files are closed and reopened. This allows removal of old log files. Also, the following attributes 
cannot be changed on reconfiguration: socket_type, wait, protocol, type. 

xinetd LOG FORMAT 

Log entries are lines with the following format: 

ent ry: service-i d data 

T he data depends on the entry. Possi ble entry types: 


START 

Generated when a server is started 

EXIT 

G enerated when a server exits 

FAIL 

Generated when it is not possi ble to start a server 

DATA 

G enerated when an attempt to start a server fails and the 
service supports the record log option. 

USERID 

Generated if the userid log option isused. 

In the following formats, the information enclosed in brackets appears if the appropriate log option isused. 

A start entry has the format 

START: service-id [pid=%d] [from=%d.%d.%d.%d] [time=t i me] 

Time is given aSyear/month/day@hour:minutes:seconds. 

An exit entry has the format 

EXIT: service-id [ type=%d] [pid=%d] [duration=%d(sec)] 

type can be either status or signal. The number is either the exit status or the signal that caused process termination. 

A FAIL entry hastheformat: 

FAIL: service-id reason [from=%d.%d.%d.%d] [time=t i me] 

Possible reasons are 

fork 

Acertainnumberofconsecutiveforkattemptsfai 1 ed (this 
number is a configurable parameter). 

time 

T hetimecheck failed. 

address 

The address check failed. 

service_limit 

The allowed number of server instances for this service would 
be exceeded. 

process_limit 

A data entry hastheformat 

DATA: service-id data 

A limiton thenumber offorked processes was specified and it 
would be exceeded. 

T he dat a logged depends on the service. 

login 

remote_user=%s local_user=%s tty=%s 

exec 

remote_user=%sverify=5tatuscommand=%sPossiblestatus 

values: 

ok The password was correct 

failed The password was incorrect 

baduser N o such user 

shell remote_user=%s local_user=%s command=%s 

finger received string OF EMPTY-LINE 
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A userid entry has the format 

USERID: text 

Thetext isthe response of theRFC 931 daemon at the remote end excluding the port numbers (which areincluded in the 
response). H ere'san example 
# 

# Sample configuration file for xinetd 

# 

defaults 

{ 

log_type = FILE /var/log/servicelog 

log_on_success = PID 

log_on_failure = HOST TIME RECORD 

only_from = 128.138.193.0 128.138.204.0 128.138.209.0 

only_from = 128.138.252.1 

instances = 10 

disabled = rstatd 

} 

# 

# Note 1: the protocol attribute is not required 

# Note 2: the instances attribute overrides the default 

# 

service login 

{ 

socket_type = stream 
protocol = tcp 
wait = no 
user = root 

server = /usr/etc/in.rlogind 
instances = UNLIMITED 

} 

# 

# Note 1: the instances attribute overrides the default 

# Note 2: the log on success flags are augmented 

# 

service shell 

{ 

socket_type = stream 

wait = no 

user = root 

instances = UNLIMITED 

server = /usr/etc/in.rshd 

log_on_success += HOST TIME RECORD 

} 

service ftp 

{ 

socket_type = stream 
wait = no 
user = root 

server = /usr/etc/in.ftpd 
server_args = -1 
instances = 4 

log_on_SUCCess += DURATION HOST USERID 
access_times = 2:00-9:00 12:00-24:00 

} 

# 

# This entry and the next one specify internal services. Since this 

# is the same service using a different socket type, the id attribute 

# is used to uniquely identify each entry 

# 



service echo 

{ 

id = echo-stream 
type = INTERNAL 
socketjtype = stream 
user = root 
wait = no 

} 

service echo 

{ 

id = echo-dgram 
type = INTERNAL 
socketjtype = dgram 
user = root 
wait = no 

} 

# 

# Sample RPC service 

# 

service rstatd 

type = RPC 
socketjtype = dgram 
protocol = udp 

server = /usr/etc/rpc.rstatd 
wait = yes 
user = root 
rpc_version = 2-4 

env = LD_LIBRARY_PATH=/etc/securelib 

} 

# 

# Sample unlisted service 

# 

service unlisted 

{ 

type = UNLISTED 
socketjtype = stream 
protocol = tcp 
wait = no 

server = /home/user/some server 
port = 20020 

} 

FILES 

Default configuration file 
Default dump file 

SEE ALSO 

inetd(8) 

Postel J., Echo Protocol, RFC 862, May 1983. 

Postel J Discard Protocol, RFC 863, M ay 1983. 

Postel J., Character Generator Protocol , RFC 864, May 1983. 

Postel J., Daytime Protocol, RFC 867, M ay 1983. 

Postel J., H arrenstien K„ TimeProtocol, RFC 868, M ay 1983. 

St. JohnsM ..Authentication Server, RFC 931, January 1985. 


/etc/xinetd.conf 

/tmp/xinetd.dump 
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AUTHOR 

P an os T si ri goti s (C S Department, University of Colorado, Boulder) 

NOTES 

When the attributes oniy_trom and no_access are not specified fora service (either directly or via defaults), the address check 
is considered successful (that is, access will not be denied). 

If the userid log option is specified and the remote RFC 931 server sends back an error reply, access will not be denied. 

If the userid log option is specified and the remote host does not run an RFC 931 server, there will be no indication in the 
log of that fact (other than the missing userid log entry). 

BUGS 

Supplementary group ID s are not supported. 

If the intercept flag is not used, access control on the address of the remote host is not performed when wait is yes and 
socket_type is stream. 

If the intercept flag is not used, access control on the address of the remote host for services where wait is yes and 
socket_type isdgram is performed only on the first packet. The server may then accept packets from hosts not in the access 
control list. Thiscan happen with RPC services. 

Unlisted RPC services are not supported; that is, all RPC services must be registered in /etc/rpc. Specifying an RPC service 
by its RPC program number is not (yet) possible. 

There is no way to put a space in an environment variable. 

When wait is yes and socket_type is stream, thesocket passed to the server can only accept connections. 

The intercept flag is not supported for internal services or multithreaded services. 

Interception works by forking a process that acts as a fi Iter between the remote host(s) and the local server. This obviously 
has a performance impact which dependson thevolumeof information exchanged. It isup to you to make the compromise 
between security and performance for each service. 

PRONUNCIATION 

xinetd is pronounced "zy-net-d." 

10 May 1992 
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xinit— X Window System initializer 

SYNOPSIS 

xinit [[client ] options ][— [ server ] [ d i s p I ay ] options ] 

DESCRIPTION 

The xinit program is used to start the X Window System server and a first client program on systems that cannot start X 
directly from /etc/init orin environments that use multiple window systems. When thisfirst client exits, xinit will kill the 
X server and then terminate. 

If no specific client program is given on the command line, xinit will look for a file in the user's home directory called 
.xinitrc to run as a shell script to start up client programs If no such file exists, xinit will use the following as a default: 


xterm -geometry +1+1 -n login -display :0 
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If no specific server program is given on the command line, xinit will look for a file in the user's home directory called 
.xsenverrc to run as a shell script to start up the server. If no such file exists, xinit will use the following as a default: 
x : 0 

N otethat this assumes that there is a program named X in the current search path. H owever, servers are usually named 
xdispiaytype where dispiaytype is the type of graphics display that is driven by this server. T he site administrator should, 
therefore, make a link to the appropriate type of server on the machine or create a shell script that runs xinit with the 
appropriate server. 

N ote, when using a .xsenverrc script be sure to mark the real X server as exec. Failing to do this can make the X server slow 
to start and exit. For example 
exec Xdispiaytype 

An important point isthat programs which are run by xinitrc should be run in the background if they do not exit right 
away, so that they don't prevent other programsfrom starting up. FI owever, the last long-lived program started (usually a 
window manager or terminal emulator) should be left in the foreground so that the script won't exit (which indicates that 
the user is done and that xinit should exit). 

An alternate client and/or server may be specified on the command line. The desired client program and its arguments 
should be given as the first command-line arguments to xinit. T o specify a particular server command line, append two 
dashes (—) to the xinit command line (after any client and arguments) followed by the desired server command. 

Both the client program name and the server program name must begin with a slash (/) or a period (.). Otherwise, they are 
treated as arguments to be appended to their respective startup lines. This makes it possible to add arguments (for example, 
foreground and background colors) without having to retype the whole command line. 

If an explicit server name is not given and the first argument following the double dash (—) is a colon followed by a digit, 
xinit will use that number asthedisplay number instead of zero. All remaining arguments are appended to theserver 
command line 

EXAMPLES 

Following are several examples of how command-line arguments in xinit are used: 

This will start up a server named X and run the user's xinitrc, if it exists, or else start an xterm: 
xinit 

Thisishow onecould start a specific type of server on an alternate display: 

xinit — /usr/XI1R6/bin/Xqdss :1 

This will start up a server named X, and will append the given arguments to the default xterm command (it will ignore 
xinitrc): 

xinit -geometry =80x65+10+10 -fn 8x13 -j -fg white -bg navy 

This will use the command xsun -1 -c to start theserver and will append the arguments -e widgets to the default xterm 
command: 

xinit -e widgets — ./Xsun -1 -c 

Thiswill start a server named X on display 1 with the arguments -a 2 -ts: 
xinit /usr/ucb/rsh fasthost cpupig -display ws:1 -- :1 -a 2 -t 5 

It will then start a remote shell on the machine fasthost in which it will run the command cpupig, telling it to display back on 
the local workstation. 

Following is a sample xinitrc that starts a clock, starts several terminals, and I eaves the window manager running as the 
"last" application. Assuming that thewindow manager has been configured properly, theuserthen chooses the Exit menu 
item to shut down X. 


xrdb -load $HOME/.Xresources 
xsetroot -solid gray & 
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xclock -g 50x50-0+0 -bw 0 & 
xload -g 50x50-50+0 -bw 0 & 
xterm -g 80x24+0+0 & 
xterm -g 80x24+0-0 & 
twm 

Sites that want to create a common startup environment could simply create a default xinitrc that references a site-wide 
startup file: 

#!/bin/sh 

. /usr/local/lib/site.xinitrc 

Another approach is to write a script that starts xinit with a specific shell script. Such scripts are usually named xii, xstart, 
or startx, and are a convenient way to provide a simple interface for novice users: 

#!/bin/sh 

xinit /usr/local/lib/site.xinitrc — /usr/XI1R6/bin/X be 

EN VIRO N MENT VARIABLES 

DISPLAY 

XINITRC 

FILES 

.xinitrc 
xterm 
.xserverre 
X 

SEE ALSO 

x(l), startx(l), Xserver(l), xterm(l) 

AUTHOR 

Bob Scheifler (M IT Laboratory for Computer Science) 

X Version 11 Release 6 


This variable gets set to the name of the display to which 
clients should connect. 

This variable specifies an init file containing shell commands 
to start up the initial windows. By default, xinitrc in the 
homedi rectory will beused. 

Default client script 
C lient to run if .xinitrc does not exist 
D efauIt server script 

Server to run if .xserverre does not exist 


xkill 

xkiii— Kill a client by itsX resource 

SYNOPSIS 

xkill [-display di spl ayname] [-id resource] [-button number] [-frame] [-all] 

DESCRIPTION 

xkiii isa utility for ford ngtheX server to close connections to clients. Thisprogram is very dangerous, butisuseful for 
aborting programs that have displayed undesired windows on a user's screen. If no resource identifier is given with -id, xkiii 
will display a special cursor as a prompt for the user to select a window to be killed. If a pointer button is pressed over a 
nonroot window, the server will close its connection to the client that created the window. 
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OPTIONS 

-display di s pi ay name 
-id resource 


-button number 


-all 


-frame 


XDEFAULTS 

Button 

SEE ALSO 

X(l), xwininfo(l), XKillClient and XGetPointerMapping in 

Specification 


This option specifies the name of theX server to contact. 
Thisoption specifies theX identifier for the resource whose 
creator isto be aborted. If no resource is specified, xkiii will 
display a special cursor with which you should select a window 
to be kill. 

This option specifies the number of pointer button that should 
be used in selecting a window to kill. If the word "any" is 
specified, any button on the pointer may be used. By default, 
the first button in the pointer map (which is usually the 
leftmost button) is used. 

Thisoption indicates that all clients with top-level windows on 
thescreen should be killed, xkiii will ask you to select theroot 
window with each of the currently defined buttons to give you 
several chances to abort. Use of thisoption ishighly discour¬ 
aged. 

Thisoption indicates that xkiii should ignore the standard 
conventions for finding top-level client windows(which are 
typically nested insideawindow manager window), and 
simply believe that you want to kill direct children of theroot. 


Specifies a specific pointer button number ortheword "any” 
to usewhen selecting windows. 


ProgrammersM anual, Kiiiciient in theX Protocol 


AUTHOR 

Jim Fulton (M IT X Consortium) and DanaChee(Bellcore) 


X Vera on 11 Release 6 


xlogo 

xiogo— X Window System logo 

SYNOPSIS 

xlogo [-tool ki topti on ...] 

DESCRIPTION 

Thexiogo program displays theX W indow System logo. 

OPTIONS 

xiogo accepts all of thestandard X T oolkit command-line options, as well as the following: 

-shape Thisoption indicates that the logo window should be shaped 

rather than rectangular. 
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RESOURCES 

The default width and the default height are each 100 pixels. This program uses the Logo widget in the Athena widget set. It 

understands all of the Simple widget resource names and classes as well as: 

foreground (class Foreground) Specifies the color for the logo. T he default depends on 

whether reverseVideo isspecified. If reverseVideo iSSpecified, 
the default is xtDefauitForeground, otherwise the default is 
XtDefaultBackground. 

shapewindow (class shapewindow) Specifies that the window is shaped to the X logo. T he default 

is False. 


WIDGETS 

In order to specify resources, it is useful to know the hierarchy of the widgets that compose xiogo. In the following notation, 
indentation indicates hierarchical structure. Thewidget class nameisgiven first, followed by thewidget instance name. 

XLogo xiogo 

Logo xiogo 

ENVIRONMENT 

display To get the default host and display number. 

xenvironment T o get the name of a resource file that overrides the global 

resources stored in the resource_manager property. 

FILES 

<xRoot>/iib/xi i /app-defauits/xLogo Specifies required resources 

SEE ALSO 

X(l), xrdb(l) 

AUTHORS 

0 IlieJ ones of Apollo Computer and Jim Fulton of the M IT X Consortium wrote the logo graphics routine, based on a 
graphic design by Danny Chong and Ross Chapman of Apollo Computer. 

X Verson 11 Release 6 
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xisatcms— List interned atoms defined on server 

SYNOPSIS 

xisatcms [-opticns ...] 

DESCRIPTION 

xisatcms lists the interned atoms By default, all atoms starting from 1 (the lowest atom value defined by the protocol) are 
listed until unknown atom isfound. If an explicit rangeisgiven, xlsatoms will try all atomsin therange, regardlessof 
whether or not any are undefined. 
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OPTIONS 

-display dpy 
-format st ri ng 


-range [I ow] - [hi gh ] 


-name st ri ng 


SEE ALSO 

X(l), Xserver(l), xprop(l) 

ENVIRONMENT 

DISPLAY 

AUTHOR 

Jim Fulton (M IT X Consortium) 


This option specifies the X server to which to connect. 

This option specifies a printf-style string used to list each 
atom <vaiue,name> pair, printed in that order (value isan 
unsigned long and name isa char *). xisatoms will supply a 
newline at the end of each line. T he default is%id\t%s. 

This option specifies the range of atom values to check. If i ow 
isnot given, avalueof i isassumed. If hi gh isnot given, 
xisatoms will stop at the first undefined atom at or abovei ow. 
This option specifies the name of an atom to list. If the atom 
does not exist, a message will be printed on the standard error. 


T o get the default host and display to use 


X Version 11 Release 6 


xlsclients 

xlsclients— List client applications running on a display 

SYNOPSIS 

xlsclients [- display di spl ayname] [-a] [-1] [-m maxcmdlen] 

DESCRIPTION 

xlsclients is a utility for listing information about theclient applications running on a display. It may be used to generate 
scripts representing a snapshot of the user's current session. 

OPTIONS 

-display di spl ayname 
-a 

-1 

-m maxcmdlen 

ENVIRONMENT 

DISPLAY 


This option specifies the X server to contact. 

Thisoption indicates that clients on all screensshould be 
listed. By default, only those clients on the default screen are 
listed. 

List in longformat, givingthewindow name, icon name, and 
class hints in addition to the machine name and command 
string shown in the default format. 

Thisoption specifies the maxi mum number of characters in a 
command to print out. The default is 10000. 


T 0 get the default host, display number, and screen. 
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SEE ALSO 

X(l), xwininfo(l), xprop(l) 

AUTHOR 

Jim Fulton (M IT X Consortium) 

X Verson 11 Release6 


xlsfonts 

xisfonts — Server font list displayer for X 

SYNOPSIS 

xlsfonts [-options ...] [-fn pattern] 


DESCRIPTION 

xlsfonts lists the fonts that match the given pattern. The wildcard character* may be used to match any sequence of 
characters (including none), and ? to match any single character. If no pattern is given, * isassumed. 

The* and ? characters must be quoted to prevent them from being expanded by the shell. 


OPTIONS 

-display host:dpy 
-1 


-11 

-111 

-m 


-C 

-1 


-w width 


-n col umns 


-u 

-0 


-fn pattern 


This option specifies the X server to contact. 

Lists some attributes of thefonton onelinein addition to its 
name. 

Lists font properties in addition to -I output. 

Lists character metrics in addition to -n output. 

This option indicates that long listings should also print the 
minimum and maximum bounds of each font. 

Thisoption indicates that listings should use multiple 
columns.Thisisthesameas-n 0. 

This option indicates that listi ngs should use a single column. 
Thisisthesameas-n 1. 

Thisoption specifies the width in characters that should be 
used in figuring out how many columns to print. The default 

is 79 . 

Thisoption specifies the number of columns to use in 
displaying the output. By default, it will attempt to fit as many 
columns of font names into the number of character specified 

by -w width. 

This option indicates that the output should be left unsorted. 
This option indicates that xlsfonts should do an openFont 
(and QueryFont, if appropriate) rather than anstFonts.Thisis 
useful if ListFonts or ListFontswithinfo fail to list a known 
font(asisthecasewith somescaled font systems). 

Thisoption specifies the font name pattern to match. 


SEE ALSO 

x(l), xserver(l), xset(l), xfd(l), X Logical Font D escription Conventions 
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ENVIRONMENT 

display To get the default host and display to use 

BUGS 

Doing xisfonts -l can tie up your server for a very long time. This is really a bug with single-threaded nonpreemptable 
servers, notwith thisprogram. 

AUTHOR 

M ark Lillibridge (M IT Project Athena), Jim Fulton (M IT X Consortium), and Phil Karlton (SGI) 

X Version 11 Releas6 


xmag 

xmag— M agnify parts of the screen 

SYNOPSIS 

xmag [ -mag magfactor ][-source geom ][—tool ki topti on ...] 

DESCRIPTION 

The xmag program allows you to magnify portions of an X screen. If no explicit region is specified, a square with the pointer 
in the upper-left corner is displayed indicating the area to be enlarged. The area can be dragged out to the desired size by 
pressing Button 2 . After a region has been selected, a window is popped up showing a blown-up version of the region in 
which each pixel in the source image is represented byasmall square of the same color. Pressing Button 1 in the enlargement 
window shows the position and RGB value of the pixel under the pointer until the button is released. T ypingq or "C in the 
enlargement window exits the program. The application has five buttons across its top. Close deletes this particular 
magnification instance. Replace brings up the rubber band selector again to select another region for this magnification 
instance. N ew brings up the rubber band selector to create a new magnification instance. Cut puts the magnification image 
into the primary selection. Paste copies the primary selection buffer into xmag. N ote that you can cut and paste between xmag 
and thebitmap program. Resizing xmag resizes the magnification area, xmag preserves the colormap, visual, and window depth 
of the source. 

WIDGETS 

xmag uses the X T oolkit and the Athena W idget Set. The magnified image is displayed in the Scale widget. For more 
information, see the Athena Widget Set documentation. Following is the widget structure of the xmag application. Indenta¬ 
tion indicates hierarchical structure. Thewidget class name isgiven first, followed by thewidget instance name. 

Xmag xmag 

RootWindow root 
TopLevelShell xmag 
Paned panel 

Paned pane2 

Command close 
Command replace 
Command new 
Command select 
Command paste 
Label xmag label 
Paned pane2 

Scale scale 

OverrideShell pixShell 
Label pixLabel 
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OPTIONS 

-source geom This option specifies the size and/or location of the source 

region on the screen. By default, a 64 x 64 square is provided 
for the user to select an area of the screen. 

-mag integer This option indicates the magnification to be used. T he 

default is5. 

AUTHORS 

Dave Stern I icht and Davor M atic (M IT X Consortium) 

X Verson 11 Releas6 


xmkmf 

xmkmf — C reate a Makefile from an Imakefile 

SYNOPSIS 

xmkmf [-a][topdin [ curdir ]] 

DESCRIPTION 

The xmkmf command is the normal way to create a Makefile from an imakef iie shipped with third-party software. 

When invoked with no argumentsin a directory containing an imakefiie, theimake program isrun with arguments 
appropriate for your system (configured into xmkmf when X was built) and generates a Makefile. 

When invoked with the -a option, xmkmf builds the Makefile in the current directory, and then automatically executes make 
Makefiles (in case there are subdirectories), make includes, and make depend for you. Thisisthenormal way to configure 
software that is outside the X Consortium build tree. 

If working inside the X Consortium build tree (unlikely unless you are an X developer, and even then this option is never 
really used), thetopdir argument should be specified as the relative path name from the current directory to the top of the 
build tree. Optionally, curdir may be specified as a relative path name from the top of the build tree to the current directory. 
It is necessary to supply curdir if the current directory has subdirectories, or the Makefile will not be able to build the 
subdirectories. If atopdir is given, xmkmf assumes nothing is installed on your system and looks for files in the build tree 
instead of using the installed versions. 

SEE ALSO 

imakef1) 

X Vera on 11 Release 6 


xmodmap 

xmodmap— Utility for modifying keymaps in X 

SYNOPSIS 

xmodmap [-options ...] [filename] 

DESCRIPTION 

The xmodmap program is used to edit and display the keyboard modifier map and keymap table that are used by client 
applications to convert event keycodes into keysyms. It is usually run from the user's session startup script to configure the 
keyboard according to personal tastes. 
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OPTIONS 

The following options may be used with xmodmap: 

Thisoption specifies the host and display to use. 

This option indicates that a brief description of the command¬ 
line arguments should be printed on the standard error 
channel. Thiswill be done whenever an unhandled argument 
is given to xmodmap. 

Thisoption indicates that a help message describing the 
expression grammar used in files and with -e expressions 
should be printed on the standard error. 

Thisoption indicates that xmodmap should print logging 
information as it parses its input. 

This option turns off the verbose logging. T his is the default. 
Thisoption indicates that xmodmap should not change the 
mappings, but should display what it would do, like make(l) 
does when given thisoption. 

Thisoption specifies an expression to be executed. Any 
number of expressions may be specified from the command 
line 

This option indicates that the current modifier map should be 
printed on the standard output. 

Thisoption indicates that the current keymap table should be 
printed on the standard output. 

Thisoption indicates that the current keymap table should be 
printed on the standard output in the form of expressions that 
can be fed back to xmodmap. 

Thisoption indicates that the current pointer map should be 
printed on the standard output. 

A lone dash meansthat the standard input should be used as 
the input file 

The filename specifies a file containing xmodmap expressions to be executed. This file is usually kept in the user's home 
directory with a name like .xmodmaprc. 

EXPRESSION GRAMMAR 

The xmodmap program reads a list of expressions and parses them all before attempting to execute any of them. This makes it 
possible to refer to keysymsthat are being redefined in a natural way without having to worry as much about name conflicts. 

keycode number = keysymname ... T he list of keysyms is assigned to the indicated keycode (which 

may be specified in decimal, hex, or octal and can be 
determined by running thexev program. 

keycode any = keysymname ... If no existing key has the specified list of keysyms assigned to 

it, a spare key on the keyboard is selected and the keysyms are 
assigned to it. The list of keysyms may be specified in decimal, 
hex, or octal. 

keysym keysymname = keysymname ... T he keysymname on the left side is translated into matching 

keycodesused to perform the corresponding set of keycode 
expressions. The list of keysym names may be found in the 


-display display 
-help 

-grammar 

-verbose 

-quiet 

-n 

-e expression 

-pm 

-pk 

-pke 
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header fi le <X11 /keysymdef. h (without the XK_pref ix) or the 
keysym database <xRoot>/iib/xn/xKeysymDB, where <xRoot> 
refers to the root of the X11 install tree. N otethat if the same 
keysym isbound to multiple keys, theexpression isexecuted 
for each matching keycode. 

This removes all entries in the modifier map for the given 
modifier, where valid names are shift, Lock, control, Modi, 
Mod2, Mod3, Mod4, andMods (case does not matter in modifier 
names, although it does matter for all other names). For 
example, clear Lock will remove any keys that were bound to 
the shift lock modifier. 

This adds all keys containing the given keysymstothe 
indicated modifier map. The keysym names are evaluated after 
all input expressions are read to make it easy to write 
expressions to swap keys. (See the "Examples" subsection). 
Thisremovesall keys contai ni ng the given keysymsfrom the 
indicated modifier map. U nlike add, the keysym names are 
evaluated asthelineisread in. T his allows you to removekeys 
from a modifier without having to worry about whether or not 
they have been reassigned. 

This sets the pointer map back to its default settings (button 1 
generates a code of 1, button 2 generates a 2, and so on). 

This sets to pointer map to contain theindicated button 
codes. The list always starts with the first physical button. 

Lines that begin with an exclamation point (i) are taken as comments 

If you want to change the binding of a modifier key, you must also remove it from the appropriate modifier map. 

EXAMPLES 

M any pointers are designed such that the first button is pressed using the index finger of the right hand. People who are left- 
handed frequently find that it is more comfortable to reverse the button codes that are generated so that the primary button 
ispressed using theindex finger of the left hand.Thiscould bedoneon a3 button pointer as follows: % xmodmap -e "pointer 

=3 2 1". 

M any applications support the notion of M eta keys (similar to Control keys except that M eta is held down instead of 
Control). H owever, some servers do not have a M eta keysym in the default keymap table so one needs to be added by hand. 
The following command will attach M eta to theM ulti language key (sometimes labeled Compose Character). It also takes 
advantage of the fact that applicationsthat need a M eta key simply need to get the keycode and don't requi re the keysym to 
be in the first column of the keymap table This means that applicationsthat are looking for a M ulti key (including the 
default modifier map) won't notice any change. Example: 

% xmodmap -e "keysym Multi_key = Multi_key Meta_L" 

Similarly, some keyboards have an Alt key but no M eta key. In that case the following may be useful: 

% xmodmap -e "keysym Alt L = Meta L Alt L" 

One of the more simple yet convenient, uses of xmodmap isto set the keyboard's "rubout" key to generate an alternate 
keysym. This frequently involves exchanging Backspace with Delete to be more comfortable to theuser. I f the ttyModes 
resource in xterm is set as well, all terminal emulator windows will use the same key for erasing characters: 

% xmodmap -e "keysym Backspace = Delete" 

% echo "XTerm*ttyModes: erase A ?" | xrdb -merge 


clear MODI FI ERNAME 

add MODI FI ERNAME = KEYSYMNAME , , 

remove MODI FI ERNAME = KEYSYMNAME 

pointer =default 
pointer = NUMBER ... 
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Some keyboards do not automatically generate less than and greater than characters when the comma and period keys are 
shifted. This can be remedied with xmodmap by resetting the bindings for the comma and period with the following scripts: 

I 

! make shift-, be $<$ and shift-, be $>$ 

i 

keysym comma = comma less 
keysym period = period greater 

One of the more irritating differences between keyboards is the location of the Control and Shift Lock keys. A common use 
of xmodmap isto swap these two keysasfollows: 

I 

! Swap Caps_Lock and Control_L 

i 

remove Lock = Caps_Lock 
remove Control = Control_L 
keysym Control_L = Caps_Lock 
keysym Caps_Lock = Control_L 
add Lock = Caps_Lock 
add Control = Control_L 

T he keycode command is useful for assigning the same keysym to multiple keycodes. Although unportable it also makes it 
possible to write scripts that can reset the keyboard to a known state. The following script sets the Backspace key to generate 
Delete (as shown earlier), flushes all existing caps lock bindings, makes the Caps Lock key be a control key, makeF5 generate 
Escape, and makes Break/Reset be a shift lock. 

I 

! On the HP, the following keycodes have key caps as listed: 

i 

! 101 Backspace 

! 55 Caps 

! 14 Ctrl 

! 15 Break/Reset 

! 86 Stop 

! 89F5 

i 

keycode 101 = Delete 
keycode 55 = Control_R 
clear Lock 

add Control = Control_R 
keycode 89 = Escape 
keycode 15 = Caps_Lock 
add Lock = Caps_Lock 

ENVIRONMENT 

display To get default host and display number 

SEE ALSO 

x(l), xev(l), xiib documentation on key and pointer events 

BUGS 

Every time a keycode expression is evaluated, the server generates a MappingNotity a/ent on every client. This can cause some 
thrashing. All of the changes should be batched together and done at once. Clients that receive keyboard input and ignore 
MappingNotity events will not notice any changes made to keyboard mappings. 

xmodmap should generate add and remove expressions automatically whenever a keycode that is already bound to a modifier is 
changed. 
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There should beaway to have the remove expression accept keycodesaswell askeysymsfor those times when you really mess 
up your mappings. 

AUTHOR 

Jim Fulton (M IT X Consortium), rewritten from an earlier version by David Rosenthal (Sun M icrosystems) 

X Verson 11 Release 6 


xon 

xon — Start an X program on a remote machine 

SYNOPSIS 

xon remote-host [-access] [-debug] [-name window-name] [-nols] [-screen screen-no] [-user user-name] [command ...] 


DESCRIPTION 

xon runs the specified command (default xterm -is) on the remote machine using rsh, remsh, or rcmd. xon passes the display, 
xauthority, and xuserfilesearchpath environment variables to the remote command. 

When no command is specified, xon runs xterm -is. It additionally specifies the application name to be xterm-r emote -host 
and thewindow titleto be -tiremote-host. 

xon can only work when the remote host will allow you to log in without a password, by having an entry in the .rhosts file 
permitting access. 


OPTIONS 


N ote that theoptionsfollow the remote hostname (asthey do with riogin). 


-access 


-debug 


-name window-name 

-nols 

-screen screen-no 

-user user-name 


Runs xhost locally to add the remote host to the host access list 
in theX server. Thiswon'twork unless xhost isgiven 
permission to modify the access list. 

Normally, xon disconnects the remote process from stdin, 
stdout, and stderrto eliminate thedaemon processes that 
usually connect them across the network. Specifying the -debug 
option leaves them connected so that error messages from the 
remote execution are sent back to the originating host. 

This specifies a different application name and window title 
for the default command (xterm). 

N ormally xon passes the -is option to the remote xterm; this 
option suspends that behavior. 

This changes the screen number of the display variable passed 
to the remote command. 

By default, xon simply uses rsh/remsh/rcmd to connect to the 
remote machine using the same username as on the local 
machine. Thisoption causes xon to specify an alternative 
username. Thiswill not work unless you have authorization to 
access the remote account, by placing an appropriate entry in 
the remote user's .rhosts file. 


BUGS 

xon can get easily confused when the remote host, username, or various environment variable values contain whitespace, 
xon has no way to send theappropriateX authorization information to the remote host. 


X Verson 11 Release 6 
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xpmtoppm 

xpmtoppm— Convert an Xll pixmap into a portablepixmap 

SYNOPSIS 

xpmtoppm [xpmf i I e ] 

DESCRIPTION 

Reads an Xll pixmap (XPM version 1 or 3) as input. Produces a portable pixmap as output. 

KNOWN BUGS 

The support to XPM version 3 is limited. Comments can only be single lines and there must be for every pixel a default 
color name for a color type visual. 

SEE ALSO 

ppmtoxpm(l), ppm(5) 

XPM Manual byArnaud LeHors(lehors@mirsa.inria.fr) 

AUTHOR 

Copyright (c) 1991 byjef Poskanzer. 

U pgraded to support XPM version 3 by Arnaud LeH ors (iehors@mirsa.inria.fr) 9 April 1991 

16 August 1990 


xprop 

xprop— Property displayer forX 

SYNOPSIS 

xprop [-help] [-grammar] [-id id] [-root] [-name name] [-frame] [-font font] 
[-display display] [-len n] [-notype] [-fs file] [-remove property-name ] 
[-spy] [-f atom format [dformat]]* [format [dformat] atom]* 


SUMMARY 

The xprop utility is for displaying window and font properties in an X server. One window or font is selected using the 
command-line arguments or possibly in the case of a window, by clicking on the desired window. A list of properties is then 
given, possibly with formatting information. 


OPTIONS 

-help 
-grammar 
-id i d 


-name name 


Print out a summary of command-line options. 

Print out a detailed grammar for all command-lineoptions. 
This argument allowstheuser to select window id on the 
command line rather than using the pointer to select the target 
window. This is very useful indebuggingX applicationswhere 
the target window is not mapped to the screen or where the 
use of the pointer might be impossible or interfere with the 
application. 

This argument allowstheuser to specify that the window 
named name is the target window on the command line rather 
than using the pointer to select the target window. 
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-font font 

-root 

-display di spi ay 
-len n 

-notype 
-fs file 

-frame 

-remove property -name 
-spy 

-f name f or mat [df or mat ] 


This argument allowstheuserto specify that the properties of 
font font should be displayed. 

This argument specifies that X's root wi ndow is the target 
window. This is useful in situations where the root window is 
completely obscured. 

This argument allows you to specify the server to connect to; 
seex(l). 

Specifies that at most, n bytes of any property should be read 
or displayed. 

Specifies that the type of each property should not be 
displayed. 

Specifies that filef i i e should beused asa sourceof more 
formats for properties. 

Specifies that when selecting a window by hand (that is, if 
neither -name, -root, nor -id is given), look atthewindow 
manager frame (if any) instead of looking for theclient 
window. 

Specifies the name of a property to be removed from the 
indicated window. 

Examine window properties forever, looking for property 
change events. 

Specifies that the format for name should bet or mat and that 
thedformatfornarne should bedformat. If df or mat is missi ng, 
■= $ 0 +\n“ is assumed. 


DESCRIPTION 

For each of these properties, its value on the selected window or font is printed using the supplied formatting information, if 
any. If no formatting information issupplied, internal defaults are used. I f a property isnot defined on the selected window 
or font, not defined is printed as the value for that property. If no property list is given, all the properties possessed by the 
selected window or font are printed. 

A window may be selected in one of four ways. First, if the desired window is the root window, the - root argument may be 
used. If the desired window isnot the root window, it may be selected in two ways on the command line, either by id 
number, such as might be obtained from xwininto, or by name if the window possesses a name. The - id argument selects a 
window by id number in either decimal or hex (must start with ex) while the -name argument selects a window by name. 

The last way to select a window does not involve the command line at all. If none of -font, -id, -name, and - root are 
specified, a crosshairs cursor is displayed and the user is allowed to choose any visible window by pressing any pointer button 
in the desired window. If it is desired to display properties of a font as opposed to a window, the -font argument must be 
used. 

Other than the preceding four arguments and the - help argument for obtaining help, and the -grammar argument for listing 
thefull grammar forthecommand line, all theother command-line arguments are used in specifying both theformatof the 
properties to be displayed and how to display them. The -len n argument specifiesthat at most, n bytes of any given 
property will be read and displayed. This is useful, for example, when displaying the cut buffer on the root window, which 
could run to several pages if displayed in full. 

Normally, each property nameisdisplayed by printing first the property namethen itstype (if it has one) in parentheses, 
followed by its value. The -notype argument specifiesthat property types should not be displayed. The -fs argument isused 
to specify a file containing a list of formats for properties, while the -f argument isused to specify the format for one 
property. 



xprop 



The formatting information for a property actually consists of two parts, a format and a dformat. The format specifies the 
actual formatting of the property (that is, is it made up of words, bytes, or longs?, and so on) while the dformat specifies how 
the property should be displayed. 

The following paragraphs describe how to construct formats and dformats. H owever, for the vast majority of users and uses, 
thisshould not be necessary as the built-in defaults contain theformatsand dformats necessary to display all thestandard 
properties. It should only be necessary to specify formats and dformats if a new property is being dealt with or the user 
dislikes the standard display format. N ew users especially are encouraged to skip this part. 

A format consists of a 0, 8, 1 6 , or 32 followed by a sequence of one or more format characters. The@, 8 ,16, or 32 specifies 
how many bits per field there are in the property. 

Zero is a special case that means use the field size information associated with the property itself. (This is only needed for 
special cases like type integer, which isactually three different types, depending on the size of the fields of the property.) 

A value of 8 means that the property is a sequence of bytes, while a value of 16 means that the property is a sequence of 
words. The difference between these two liesin thefact that thesequenceof words will be byte swapped whilethesequence 
of bytes will not be when read by a machine of the opposite byte order of the machine that originally wrote the property. For 
more information on how properties are formatted and stored, consult the Xlib manual. 

After the size of the fields has been specified, it is necessary to specify the type of each field (is it an integer, a string, an atom, 
or what?) This is done using one format character per field. If there are more fields in the property than format characters 
supplied, the last character will be repeated as many times as necessary for the extra fields. The format characters and their 
meaning are as follows: 

a Thefield holds an atom number. A field of this type should be 

of size 32. 

b Thefield is a Boolean. A 0 means false while anything else 

means true. 

c Thefield isan unsigned number, a cardinal, 

i Thefield is a signed integer, 

m Thefield is a set of bitflags, 1 meaning on. 

s Thisfield and the next ones—until either a 0 or the end of the 

property— represent a sequence of bytes. T his format character 
is only usable with afield size of 8 and is most often used to 
represent a string. 

x Thefield isahex number (like c but displayed in hex—most 

useful for displaying window ids and the like). 

An example format is32ica, which is the format for a property of three fields of 32 bits each— thefirst holding a signed 
integer, thesecond an unsigned integer, and thethird an atom. 

The format of a dformat, unlike that of a format, is not so rigid. The only I imitations on a dformat isthatonemay not start 
with a letter or a dash. This is so that it can be distinguished from a property name or an argument. A dformat is a text string 
containing special characters instructing that various fields beprinted at various points in a manner similar to the formatting 
string used by printf. For example the dformat is ( $ 0 , $1 \)\n would render the point 3,-4, which has a format of 32ii as 

is ( 3, -4 )\n. 

Any character other than a $, ?, \, or a ( in a dformat prints as itself. T 0 print out a$, ?, \, or (, precede it with a\. For 
example, to print out a$, use \$. Several special backslash sequences are provided as shortcuts. \n will cause a newline to be 
displayed, while \t will cause a tab to be displayed. \o, where 0 isan octal number, will display character number 0 . 

A $ followed by a number n causes field number n to be displayed. The format of the displayed field depends on the 
formatting character used to describe it in the corresponding format. In other words, if a cardinal is described by c, it will 
print in decimal, while if it is described by an x, it is displayed in hex. 
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If thefield isnot present in the property (this is possible with some properties), <fieid not avaiiabie> isdisplayed instead. 
$n+ will display field number n, then a comma, then field number n+i, then another comma, then ... until the last field 
defined. If field n isnot defined, nothing isdisplayed. This is useful for a property that is a list of values. 

A ? is used to start a conditional expression, a kind of if-then statement. ?exp (text ) will display text if and only if exp 
evaluates to non-zero. This is useful for two things. First, it allows fields to bedisplayed if and only if aflag is set. And 
second, it allows a value such as a state number to bedisplayed as a name rather than as just a number. The syntax of exp is as 
follows: 

exp :: = term | t er m=exp j !exp 
term : := n j $n j mn 

The i operator is a logical not, changi ng 0 to 1 and any non-zero value to 0 . = is an equality operator. N otethat internally, all 
expressions are evaluated as 32-bit numbers, so -1 isnot equal to 65535 . = returns 1 if the two values are equal and 0 if not. n 
represents the constant value n while $n represents the value of field number n. mn is 1 if flag number n in the first field 
having format character m in the corresponding format is 1 ; 0 otherwise. 

Examples: ?m3( count: $3 \ n ) displays field 3 with a label of count if and only if flag number 3 (count starts at 01 ) is on. 

?$ 2=0 (True) ?! $ 2=0 (False ) displays the inverted valueof field 2 asa Boolean. 

In order to display a property, xprop needs both a format and a dformat. Before xprop uses its default values of a format of 32x 
and a dformat of" = { $ 0 + }\n", it searches sa/eral placesin an attempt to find more specific formats. First, asearch ismade 
using the name of the property. If this fails, asearch is made using the type of the property. This allows type string to be 
defined with one set of formats while allowing property wm_name, which is of type string to be defined with a different 
format. I n thisway, the display formats for a given type can be overridden for specific properties. 

The locations searched are in order: the format, if any, specified with the property name (as in 8x wm_name), the formats 
defined by -f options in last to first order, the contents of the file specified by the - ts option if any, the contents of the file 
specified by the environmental variablexpROPFORMATs if any, and finally xprop's built-in fi le of formats. 

The format of the files referred to by the -fs argument and thexpROPFORMATs variable is one or more lines of the following 
form: 

n a me f o r ma t [dformat ] 

Where name is either the name of a property or the name of a type format is the format to be used with name, and dformat is 
the dformat to be used with name. If dformat isnot present, "=$ 0 +\n" is assumed. 

EXAMPLES 

To display the nameof the rootwindow: xprop -root wm_name 
To display the window manager hints for the clock: xprop -name xciock wm_hints 
To display the start of the cut buffer: xprop -root -ien 100 cut_buffer 0 
To display the point size of the fixed font: xprop -font fixed point_size 
To display all the properties of window #0x200007: xprop -id 0 x 200007 

ENVIRONMENT 

display To get default display. 

xpropformats Specifi es the name of a fi le from which additional formatsare 

to be obtained. 

SEE ALSO 

x( 1), xwininfo(l) 
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M ark Lillibridge (MIT Project Athena) 
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xrdb — X server resource database utility 


SYNOPSIS 


xrdb [-option ...] [filename] 


DESCRIPTION 


xrdb is used to get or set the contents of the resource_manager property on the root window of screen 0 , or the 
screen_resources property on the root window of any or all screens, or everything combined. You would normally run this 

program from yourX startup file 


M ostX clients use the resource_manager and screen_resources properties to get user preferences about color, fonts, and so on 
for applications. H aving this information in the server (where it is avail able to all clients) instead of on disk solves the 
problem in previous versions of X that required you to maintain defaults files on every machine that you might use. It also 

allows for dynamic changing of defaults without editing files. 


TheREsouRCE_MANAGER property is used for resources that apply to all screens of the display. The screen_resources property 
on each screen specifies additional (or overriding) resources to be used for that screen. (When there is only one screen, 
screenresources is normally not used; all resources are just placed in theREsouRCEjiANAGER property.) 

The file specified by filename (or the contents from standard input if - or no filename is given) is optionally passed through 
theC preprocessor with thefollowing symbols defined, based on the capabilities of theserver being used: 

SERVERHOST=host name 

The host name portion of the display to which you are 
connected. 

SRVR_n a me 

T he sERVERHosThostnamestring turned into a legal identifier. 

For example, my-dpy.lcs.mit.edu beCOmeSSRVR my dpy lcs 


mit edu. 

HOST=host name 

T he same as serverhost. 

DISPLAY_NUM=nu m 

The number of the display on theserver host. 

CLIENTHOST=host name 

T he name of the host on which xrdb is running. 

CLNTji a me 

ThecnENTHosT hostname string turned into a legal identifier. 

For example, "expo.lcs .mit. edu" becomes CLNT expo lcs Blit 


edu. 

RELEASED um 

T he vendor release number for the server. T he interpretation 
of this number will vary depending on vendor. 

REVISIONS urn 

Thex protocol minor version supported by this server 
(currently 0 ). 

VERSIONS um 

Thex protocol major version supported by this server (should 
always ben). 

VENDOR-'vendor " 

A string li teral specifying the vendor of the server. 

VNDR_n a me 

ThevENDOR name string turned into alegal identifier. For 
example, "mit x consortium" becomes vndr mit_x Consortium. 

EXT_n a me 

A symbol is defined for each protocol extension supported by 
theserver. Each extension string nameisturned into alegal 
identifier. For example, "xgd-pex 11 becomes extjodpex. 
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NUM_SCREENS=num 
SCREEN_NUM=n u m 
BITS_PER_RGB=num 


CLASS=v i s u a I cI a s s 


CLASS_vi sual cl ass=vi sual i d 
COLOR 

CLASS_visualclass_depth=num 


HEIGHT=num 

WIDTH=num 

PLANES=num 

X_RESOLUTION=num 

Y_RESOLUTION=num 


The total number of screens. 

The number of the current screen (from zero). 

The number of significant bits in an RGB color specification. 
T his is the log base 2 of the number of distinct shades of each 
primary that the hardware can generate. N otethat it usually is 
not related to planes. 

One Of StaticGray, Grayscale, StaticColor, Pseudocolor, 
TrueColor, DirectColor. This is the visual Class Of the root 
window. 

The visual class of the root window in a form you can #itdef 
on.Thevalueisthenumeric id of the visual. 

D efi ned only if CLASS is one Of StaticColor, Pseudocolor, 
TrueColor, OT DirectColor. 

A symbol is defined for each visual supported for the screen. 
Thesymbol includes the class of the vi sual and its depth; the 
value isthe numeric id of the visual. (If more than one visual 
has the same class and depth, the numeric id of the first one 
reported by the server is used.) 

Theheight of the root window in pixels. 

Thewidth of therootwindow in pixels. 

T he number of bit planes (the depth) of the root wi ndow. 

T hex resolution of the screen in pixels per meter. 

They resolution of the screen in pixels per meter. 


sRVR_name, cLNT_name, vNDR_name, and EXT_name identifiers are formed by changing all characters other than letters and digits 
into underscores. 

Lines that begin with an exclamation mark (i) are ignored and may be used as comments 

N otethat si nee xrdb can read from standard input, it can be used to change the contents of properties directly from a 
terminal or from a shell script. 


OPTIONS 

xrdb program accepts the following options 

-help Thisoption (or any unsupported option) will causeabrief 

description of the allowable options and parameters to be 
printed. 

-display display This option specifiesthe X server to be used; see x(l). It also 

specifies the screen to use for the-screen option, and it 
specifies the screen from which preprocessor symbols are 
derived for the -global option. 

-ail Thisoption indicates that operation should be performed on 

the screen-independent resource property (resource_manager), 
as well as the screen-specific property (screen_resources) on 
every screen of thedisplay. For example, when used in 
conjunction with -query, the contents of all properties are 
Output. For -load, -override, and -merge, the input file is 
processed once for each screen. The resources that occur in 
common in the output for every screen are collected, and these 
are applied as the screen-independent resources. The 
remaining resources are applied for each individual per-screen 
property. Thisthedefault mode of operation. 



-global 

-screen 

-screens 

-n 

-quiet 

-cpp filename 

•nocpp 

-symbols 

-query 


-load 

-override 

-merge 

-remove 

-retain 

-edit f i I ename 


Thisoption indicates that theoperati on should only be 
performed on the screen-independent resource_manager 
property. 

Thisoption indicates that theoperation should only be 
performed on the screen resources property of the default 
screen of thedisplay. 

Thisoption indicates that the operation should be performed 
on thescREEN REsouRCEs property of each screen of thedisplay. 
For -load, -override, and -merge, the input fi le is processed for 
each screen. 

Thisoption indicates that changesto the specified properties 
(when used with -load, -override, or -merge) or to the resource 
file (when used with -edit) should be shown on the standard 
output, but should not be performed. 

This option indicates that warning about dupl icate entries 
should not be displayed. 

Thisoption specifies the pathname of the C preprocessor 
program to be used. Although xrdb was designed to use CPP, 
any program that acts as a filter and acceptsthe -D, -i, and -u 
options may be used. 

Thisoption indicates that xrdb should not run the input file 
through a preprocessor before loading it into properties. 

This option indicates that the symbols that are defined for the 
preprocessor should be printed onto the standard output. 

This option indicates that the current contents of the specified 
properties should be printed onto the standard output. N ote 
that si nee preprocessor commands in the input resource file are 
part of the input file not part of the property, they won't 
appear in the output from thisoption. The -edit option can 
be used to merge the contents of properties back into the input 
resource fi le without damagi ng preprocessor commands. 
Thisoption indicates that the input should be loaded as the 
new value of the specified properties, replacing whatever was 
there; that is, theold contents are removed. This is the default 
action. 

Thisoption indicates that the input should be added to, 
instead of replacing, the current contents of the specified 
properti es. N ew entri es overri de previ ous entri es. 

This option indicates that the input should be merged and 
lexicographically sorted with, instead of replacing, the current 
contents of the specified properties. 

Thisoption indicates that the specified properties should be 
removed from the server. 

Thisoption indicates that the server should be i nstructed not 
to reset if xrdb isthefirst client. This should never be necessary 
under normal conditions, sincexdm and xinit always act as the 
first client. 

This option indicates that the contents of the specified 
properties should be edited into the given file replacing any 
values already listed there. This allows you to put changes that 
you have made to your defaults back into your resource file, 
preserving any comments or preprocessor lines. 
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684 

-backup string 
-Dname [=v a I ue ] 

-Una me 
-Idi rectory 

FILES 

Generalizes -/.xdefauits files 

SEE ALSO 

x(l), Xlib Resource M anager documentation, xt resource documentation 

ENVIRONMENT 

display T o figure out which display to use. 

BUGS 

The default for no arguments should be to query, not to overwrite, so that it is consistent with other programs. 

AUTHORS 

Bob Scheifler and Phil Karlton, rewritten from theoriginal byjim Gettys 

X Verson 11 Release 6 


Thisoption specifies a suffix to be appended to the filename 
used with -edit to generate a backup file. 

Thisoption is passed through to the preprocessor and is used 
to define symbols for use with conditionals such as#itdef. 
Thisoption is passed through to the preprocessor and is used 
to remove any definitions of thissymbol. 

Thisoption is passed through to the preprocessor and is used 
to specify a directory to search for files that are referenced with 
#include. 


xrefresh 

xref resh— Refresh all or part of an X screen 

SYNOPSIS 

xrefresh [-option ... ] 

DESCRIPTION 

xrefresh is a simple X program that causes all or part of your screen to be repainted. This is useful when system messages 
have messed up your screen, xrefresh maps a window on top of the desired area of the screen and then immediately unmaps 
it, causing refresh events to be sent to all applications. By default, a window with no background is used, causing all 
applications to repaint smoothly. H owever, the various options can be used to indicate that a solid background (of any color) 
or the root window background should be used instead. 

ARGUMENTS 

-white U se a white background. T he screen just appearsto flash 

quickly, and then repaint. 

-black Use a black background (in effect, turning off all of the 

electron guns to thetube). T hiscan be somewhat disorienting 
as everythi ng goes black for a moment. 

-solid color U se a solid background of the specified color. T ry green. 

U se the root wi ndow background. 


-root 
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-none 

-geometry WxH+X+Y 
-display di spi ay 

X DEFAULTS 

Thexrefresh program usestheroutinexGetDefauit(3X) to 

Black, White, Solid, None, Root 

Geometry 

ENVIRONMENT 

DISPLAY 

SEE ALSO 

X(l) 


This is the default. All of the windows simply repaint. 
Specifies the portion of the screen to be repainted; seex(l). 
This argument allows you to specify the server and screen to 
refresh; seex(l). 

id defaults, so its resource names are all capitalized. 
Determines what sort of window background to use 
Determines the area to refresh. N ot very useful. 

To get default host and display number. 


BUGS 

It should have just one default type for the background. 

AUTHORS 

Jim G ettys (D igital Equipment Corporation, M IT Project Athena) 
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Xserver 

xserver— X Window System display server 

SYNOPSIS 

X [option ...] 

DESCRIPTION 

x isthe generic namefortheX Window System display server. 11 isfrequently a link or a copy of the appropriate server 
binary for driving the most frequently used server on a given machine. 

STARTING THE SERVER 

Thex server is usually started from theX Display M anager program xdm(l). This utility is run from the system boot files and 
takes care of keeping the server running, prompting for usernames and passwords, and starting up the user sessions. 

Installations that run more than onewindow system may need to usethexinit(l) utility instead of xdm. H owever, xinit isto 
be considered a tool for buildi ng startup scripts and is not intended for use by end users. Site administrators are strongly 
urged to use xdm, or build other interfaces for novice users. 

Thex server may also be started directly by the user, though this method is usually reserved fortesting and is not recom¬ 
mended for normal operation. On some platforms the user must have special permission to start thex server, often because 
access to certain devices. (For example /dev/mouse is restricted.) 

When thex server starts up, it typically takes over the display. If you are running on a workstation whose console isthe 
display, you may not be able to log into the console while the server is running. 
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OPTIONS 

All of thex servers accept thefollowing command-line options: 

: d i s p 1 a y n u mb e r 

Thex server runs as the given d i s pi ay number , which by default 
is 0 . If multiplex servers are to run simultaneously on a host, 
each must have a unique display number. Seethe"D isplay 

N ames" subsection of thex(l) manual page to learn how to 
specify which display number clients should try to use. 

-a number 

Sets pointer acceleration (that is, the ratio of how much is 
reported to how much theuser actually moved the pointer). 

-ac 

D isables host-based access control mechanisms. Enables access 
by any host, and permits any host to modify the access control 
list. Usewith extreme caution. This option exists primarily for 
running test suites remotely. 

-audit 1 evel 

Sets the audit trail level. The default level isl, meaning only 
connection rejections are reported. Level 2 additionally reports 
all successful connectionsand disconnects. La/el 0 turns off 
the audit trail. Audit lines are sent as standard error output. 

-auth aut hori zation- fi 1 e 

Specifies a file which contains a collection of authorization 
records used to authenticate access. See also thexdm and 
xsecurity manual pages. 

be 

D isables certain kinds of error checking, for bug compatibility 
with previous releases (for example to work around bugs in 

R2 and R3 xterms and toolkits). D eprecated. 

-bs 

D isables backing store support on all screens. 

-c 

T urns off key-click. 

c vol ume 

Sets key-dick volume (allowable range 0-100). 

-cc class 

Sets the visual class for the root window of color screens. The 
class numbers are as specified in thex protocol. N ot obeyed by 
all servers. 

-co f i 1 ename 

Sets name of RG B color database. T he default is <xRoot>/iib/ 
xi i /rgb, where <xroot> refers to the root of the X11 install 
tree. 

-config f i 1 ename 

Reads more options from thegiven file. Options in thefile 
may be separated by newlines if desired. If a # character 
appears on a line all characters between it and the next 
newline are ignored, providing a simple commenting facility. 

T he -config option itself may appear in thefile. 

-core 

C auses the server to generate a core dump on fatal errors 

-dpi resolution 

Sets the resolution of the screen, in dots per inch. T o be used 
when the server cannot determine the screen size from the 
hardware. 

-deferglyphs whi chfonts 

Specifies the types of fonts for which the server should attempt 
to use deferred glyph loading, whi chfonts can bean (all fonts), 
none (no fonts), or 16 (16-bit fonts only). 

-f v o 1 u me 

Setsfeep (bell) volume (allowable range: 0-100). 

-fc cursorFont 

Sets default cursor font. 

-fn font 

Sets the default font. 
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-fp fontPath 


-I 


-kb 

-p mi nut es 
-pn 


-r 

r 

-s mi nut es 


Sets the search path for fonts This path is a comma-separated 
list of di rectories that the X server searches for font databases, 
-help prints a usage message. 

Causes all remaining command-line arguments to be ignored. 
D isables the xkeyboard extension if present. 

Sets screen saver pattern cycletimein minutes. 

Perm its the server to continue running if it fails to establish all 
of its well-known sockets (connection points for clients), but 
establishes at least one. 

T urns off auto-repeat. 

T urns on auto-repeat. 

Sets screen saver time-out time in minutes. 


-su 

-t number 


-terminate 


-to seconds 


Disables save under support on all screens. 

Sets pointer acceleration threshold in pixels (that is, sets after 
how many pixels pointer acceleration should take effect). 
Causes the server to terminate at server reset, instead of 
continuing to run. 

Sets default connection time-out in seconds. 


-tst 

ttyx* 

V 

-V 


-wm 


-x extension 


Disables all testing extensions (for example, xtest, xTrap, 

XTestExtensionl). 

Ignored, for servers started the ancient way (from init). 

Sets video-off screen saver preference. 

Sets video-on screen saver preference 
Forces the default backing-store of all windows to bewhen- 
Mapped. T his is a backdoor way of getting backing-store to 
apply to all windows. Although all mapped windows will have 
backing-store, the backing-store attribute value reported by the 
server for a window will be the last value established by a 
client. If it has never been set by a client, the server will report 
the default value, Notusetui. This behavior is requi red by the 
x protocol, which allows the server to exceed theclient's 
backing-store expectations but does not provide a way to tell 
the client that it is doing so. 

Loads the specified extension at init. This is a no-op for most 
implementations. 


SERVER DEPENDENT OPTIONS 

Somex servers accept the following options: 

-id kilobytes Sets the data space limit of the server to the specified number 

ofkilobytes. A value of zero makes the data size as large as 
possible The default value of-i leaves the data space limit 
unchanged. 

-it files Sets the number-of-open-files limit oftheserver to the 

specified number. A value of zero makes the limit as large as 
possible The default value of-i leavesthelimit unchanged. 

-is kilobytes Sets the stack space limit of the server to the specified number 

ofkilobytes. A value of zero makesthestacksizeaslargeas 
possi ble T he default value of -i leaves the stack space li mit 
unchanged. 
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-logo T urns on theX Window System logo display in the screen 

saver. There is currently no way to change this from a client. 

noiogo Turns off the X Window System logo display in the screen 

saver. There is currently no way to change this from a client. 


XDMCPOPTIONS 


x servers that supportXD M CP havethefollowing options. (SeetheX Display M anager Control Protocol specification for 
more information.) 


-query host ■ name 
-broadcast 

-indirect host■ name 
-port port-n u m 
-class di spl ay-cl ass 

-cookie xdm-auth-bits 

-displaylD display-id 


Enable XD M CP and send Query packets to the specified host. 
EnableXDM CP and broadcast BroadcastQuery packetstothe 
network. The first responding display manager will be chosen 
for the session. 

E nable X D M C P and send indirectQuery packets to the 
specified host. 

Use an alternate port number for XD M CP packets. M ust be 
Specified before any -query, -broadcast, Or -indirect options. 
XD M CP has an additional display qualifier used in resource 
lookup for display-specific options. T his option sets that value; 
by default it is MiT-unspecified (not a very useful value). 

When testing xdm-authentication-1, a private key is shared 
between theserver and themanager. Thisoption setsthevalue 
of that private data (not that it is very private, being on the 
command line!). 

Yet another XD M CP-specific value, this one allows the display 
manager to identify each display so that it can locate the 
shared key. 


XKEYBOARD OPTIONS 


x servers that support the xkeyboard extension accept the following options: 


-xkbdin di rectory 
-xkbmap f i I ename 
[+-]accessx 
-arl mi I I i seconds 

-ar2 mi I I i seconds 


Base directory for keyboard layout files 

Keyboard description to load on startup 

Enable(+) ordisable(-) AccessX key sequences 

Sets the length oftimein millisecondsthatakeymust be 

depressed before auto-repeat starts 

Sets the length oftimein milliseconds that should elapse 

between auto-repeat-generated keystrokes 


M any servers also have device-specific command-line options See the manual pages for the individual servers for more 
details. 


NETWORK CONNECTIONS 

Thex server supports client connections via a platform-dependent subset of thefollowing transport types: TCPIP, U NIX 
Domain sockets, D EC net, and several varieties of SVR4 local connections. Seethe "D isplay N ames" subsection of thex(l) 
manual page to learn howto specify which transport type clients should try to use. 

SECURITY 

Thex server implements a platform-dependent subset of thefollowing authorization protocols: -mit-magiccookie-i, xdm- 
authorization -1, sun-des-1, and mit-Kerberos- 5 . See the xsecurity(l) manual page for information on the operation of these 
protocols 
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Authorization data required by the preceding protocols is passed to the server in a private file named with the-auth 
command-line option. Each time the server is about to accept the first connection after a reset (or when the server is 
starting), it reads this file. If this file contains any authorization records, the local host is not automatically allowed access to 
the server, and only clients that send one of the authorization records contained in the file in the connection setup informa¬ 
tion will be allowed access. Seethexau manual page for a description of thebinary format of thisfile Seexauth(l) for 
maintenanceof thisfile and distribution of its contents to remotehosts. 

T hex server also uses a host-based access control list for deciding whether or not to accept connections from clients on a 
particular machine If no other authorization mechanism is being used, this list initially consistsof the host on which the 
server is running as well as any machines listed in the file /etc/xn .hosts, where n is the display number of the server. Each 
line of the file should contain either an Internet hostname (for exampleexpo.ics.mit.edu) or a D EC net hostname in double 
colon format (for example, hydra: :). There should be no leading or trailing spaces on any lines. For example, 

joesworkstation 
corporate.conpany.com 
star:: 
bigcpu:: 

Users can add or remove hosts from this list and enable or disable access control using the xhost command from the same 
machine as the server. 

Thex protocol intrinsically does not have any notion of window operation permissions or place any restrictions on what a 
client can do; if a program can connect to a display, it has full run of the screen. Sites that have better authentication and 
authorization systems might wish to make use of the hooks in the libraries and the server to provide additional security 
models. 

SIGNALS 

Thex server attaches special meaning to thefollowing signals: 

SIGHUP 


SIGTERM 

SIGUSR1 


FONTS 

Thex server can obtain fonts from directories or from font servers. The list of directories and font servers thex server uses 
when trying to open a font is controlled by the font path. 

The default font path is 

<XRoot>/lib/X11/fonts/misc/, 

<XRoot>/lib/X11/fonts/Speedo/, 

<XRoot>/lib/X11/fonts/Typel/, 

<XRoot>/lib/X11/fonts/75dpi/, 

<XRoot>/lib/X11/fonts/100dpi/ 

where <xRoot> refers to the root oftheXll install tree. 

Thefont path can beset with the-fp option or by xset(l) after the server has started. 


T his signal causes the server to close all existing connections 
free all resources, and restore all defaults It issent by the 
display manager whenever themain user'smain application 
(usually an xterm or window manager) exits to force the server 
to clean up and prepare for the next user. 

Thissignal causes the server to exit cleanly. 

This signal is used quite differently from either of the above. 
W hen the server starts, it checks to see if it has i nherited 
sigusri assiG_iGN instead of the usual sig_dfl. In thiscase, 
the server sends a sigusri to its parent process after it has set 
up the various connection schemes, xdm usesthisfeatureto 
recognize when connecting to the server is possible 
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FILES 

/etc/Xn.hosts 

<XRoot>/lib/X11/fonts/misc 
<XRoot>/lib/X11/fonts/75dpi 
<XRoot>/lib/X11/fonts/100dpi 
<XRoot>/lib/X11/fonts/Speedo 
<XRoot>/lib/X11/fonts/Typel 
<XRoot>/lib/X11/fonts/PEX 
<XRoot>/lib/X11/rgb.txt 
/trap/.XI1-unix/Xn 
/tmp/rcXn 
/usr/adm/Xnmsgs 

<XRoot>/lib/X11/xdm/xdm-errors 

Note: <xRoot> refers to the root oftheXll install tree. 


Initial access control list for display number n 


Bitmap font directories 

Outlinefont directories 
PEX font directories 
Color database 

UNIX domain socket for display number n 
Kerberos5 replay cachefor display number n 
Errorlogfilefor display numbern if run from init(8) 
Default error log file if the server is run from xdm(l) 


SEE ALSO 

General information: x(l) 

Protocols: X Window System Protocol, TheX Font Service Protocol, X Display Manager Control Protocol 
Fonts: bdftopcf(l), mkfontdir(l), xfs(l), xisfonts(l), xfontsei(l), xfd(l), X Logical Font D escription Conventions 
Security: Xsecurity(l), xauth(l), xau(l), xdm(l), xhost(l) 

Starting the server: xdm(l), xinit(l) 

Controlling the server once started: xset(l), xsetroot(l), xhost(l) 

Server-Specific man pages: Xdec(l), XmacIl(l), Xsun(l), Xnest(l), Xvfb(l), XF86 Accel(l), XF86 Mono(l), XF86 SVGAfI), XF86 
VGA16(1), XFree86(l) 

Server internal documentation: "D efinition of the Porting Layer for the X vll Sample Server/' "Strategies for Porting the X 
vll Sample Server," "G odzilla's G uide to Porting theX vll SampleServer" 

AUTHORS 

The sample server was originally written by Susan Angebranndt, Raymond D rewry, Philip Karlton, and T odd N ewman, 
from D igital Equipment Corporation, with support from a large cast. It has since been extensively rewritten by Keith 
Packard and Bob Scheifler, from M IT. 
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xset—User preferenceutilityforX 

SYNOPSIS 

xset [-display display] [ - b ] [b on/off] [b [volume [pitch [duration]]] [[-] be] 
[-c] [c on/off] [c [volume]] [ [-+]fp[-+=] path [, p a th [,...]] ] [fp default] 

[fp rehash] [[ - ]led [integer]] [led on/off] [m[ouse] [accel _mul t [/accel _di v] 
[threshold]]] [ m [ouse ] default] [p pixel color] [ [ - ] r [ keycode ] ] [ r on/off] 

[s [length [period]]] [s blank/noblank] [s expose/noexpose] [s on/off] 

[s default] [s activate] [s reset] [q] 
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DESCRIPTION 

This program is used to set various user preference options of the display. 

OPTIONS 

-display di spi ay 

Thisoption specifies the server to use; seex(l). 

b 

T he b option controls bell volume, pitch, and duration. This 
option accepts up to three numerical parameters, a preceding 
dash (-), or an on/off flag. If no parameters are given, or the on 
flag isused, thesystem defaults will be used. If the dash or oft 
is given, the bell will be turned off. If only one numerical 
parameter is given, the bell volume will be set to that value, as 
a percentage of its maxi mum. Likewise, the second numerical 
parameter specifies the bell pitch, in hertz, andthethird 
numerical parameter specifies the duration in milliseconds. 
Notethatnotall hardware can vary the bell characteristics. 

Thex server will set thecharacteri sties of the bell as closely as 
it can to the user's specifications. 

be 

Thebe option controls bug compatibility mode in the server, 
if possible; a preceding dash (-) disables the mode; otherwise, 
the mode is enabled. Variouspre-R4 clients pass illegal values 
in some protocol requests, and pre-R4 servers did not correctly 
generate errors in these cases. Such clients when run against 
an R4 server, will terminate abnormally or otherwise fail to 
operate correctly. Bug compatibility mode explicitly reintro¬ 
duces certain bugs into thex server, so that many such clients 
can still be run. Thismodeshould beused with care new 
application development should bedonewith thismode 
disabled. The server must support the mit-sundry- nonstandard 
protocol extension in order for this option to work. 

c 

Thee option controls key click. Thisoption can take an 
optional value, a preceding dash (-), or an on/off flag. If no 
parameter or theon flag is given, thesystem defaults will be 
used. If the dash or off flag isused, key click will be disabled. 

If a valuefrom 0 to 100 is given, it isused to indicate volume, 
as a percentage of the maximum. Thex server will set the 
volume to the nearest value that the hardware can support. 

fp= path,... 

Thefp= sets the font path to the entries given in the path 
argument. The entries are interpreted by the server, not by the 
client. Typically, they are directory names or font server 
names, but the interpretation is server-dependent. 

fp default 

The default argument causes the font path to be reset to the 
server's default. 

fp rehash 

The rehash argument resets the font path to its current value, 
causing the server to reread the font databases in the current 
font path. This is generally only used when adding new fonts 
to a font directory (after running mkfontdir to re-createthe 
font database). 

-fp Of fp- 

The-fp and fp- options remove elements from thecurrent 
font path. They must be followed by a comma-separated list of 
entries. 
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led 
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Thistp and fp options prepend and append elements to the 
current font path, respectively. They must be followed by a 
comma-separated list of entries. 

The led option controls the keyboard leds. This controls the 
turning on or off of one or all of the leds. It accepts an 
optional integer, a preceding dash (-) or an on/off flag. If no 
parameter or the on flag is given, all leds are turned on. If a 
preceding dash or the flag off isgiven, all leds are turned off. 

If a value between 1 and 32 isgiven, that led will be turned 
on or off depending on the existence of a preceding dash. A 
common led that can be controlled isthecaps Lock led. xset 
led 3 would turn led #3 on. xset -led 3 would turn it off. 

T he particular led values may refer to different leds on 
different hardware. 

Them option controlsthe mouse parameters. T he parameters 
for the mouse are acceleration and threshold. T he accelera¬ 
tion can be specified as an integer, or as a simple fraction. The 
mouse, orwhatever pointer the machine is connected to, will 
go acceleration ti mesas fast when it travels more than 
threshold pixels in a short time T hisway, the mouse can be 
used for precise alignment when it is moved slowly, yet it can 
be set to travel across the screen in aflick of the wrist when 
desired. Oneorboth parameters for them option can be 
omitted, but if only one is given, it will be interpreted as the 
acceleration. If no parameters or the flag default is used, the 
system defaults will beset. 

Thep option controlspixel color values. The parameters are 
thecolor map entry number in decimal, and a color specifica¬ 
tion. T he root background colors may be changed on some 
servers by altering the entries for BiackPixei and whitePixei. 
Although these are often 0 and 1 , they need not be. Also, a 
server may choose to allocate those colors privately, in which 
case an error will be generated. The map entry must not be a 
read-only color, or an error will result. 

Ther option controlsthe auto-repeat. If a preceding dash 
or the off flag is used, auto-repeat will be disabled. If no 
parameters or the on flag is used, auto-repeat will be enabled. 

If a specific keycode is specified as a parameter, auto-repeat 
for that keycode is enabled or disabled. 

Thes option lets you setthescreen saver parameters. This 
option accepts up to two numerical parameters, a blank/ 
noblank flag, an expose/noexpose flag, an on/off flag, an 
activate/reset flag, or the default flag. If no parameters or 
the default flag is used, the system will be set to its default 
screen saver characteristics. The on/off flags simply turn the 
screen saver functions on or off. The activate flag forces 
activation of screen saver even if the screen saver had been 
turned off. T he reset flag forces deactivation of screen saver 
if it is active. The blank flag sets the preference to blank the 
video (if the hardware can do so) rather than display a 
background pattern, whilenobiank sets the preference to 
display a pattern rather than blank thevideo. The expose flag 
sets the preference to allow wi ndow exposures (the server can 
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freely discard window contents), whilenoexpose sets the 
preference to disable screen saver unless the server can 
regenerate the screens without causing exposure events T he 
length and period parameters for the screen saver function 
determines how long the server must be inactive for screen 
saving to activate, and the period to change the background 
pattern to avoid burn in. The arguments are specified in 
seconds. If only one numerical parameter isgiven, it will be 
used for the length. 

q Theq option gives you information on the current settings. 

T hese settings will be reset to default values when you logout. 

N otethat not all x implementations are guaranteed to honor all of these options. 

SEE ALSO 

X(l), Xserver(l), xmodmap(l), xrdb(l), xsetroot(l) 

AUTHOR 

Bob Scheifler (M IT Laboratory for Computer Science), David Krikorian (M IT Project Athena; X11 version) 
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xsetroot— Rootwindow parameter setting utility forx 

SYNOPSIS 

xsetroot [-help] [ - def] [-display di spl ay ] [-cursor cursorfiIe maskfile] 

[-cursor_name cursorname] [-bitmap filename] [-mod x y] [-gray] [-grey] 

[ - fg col or ] [ -bg col or ] [-rv] [-solid color] [-name st ri ng ] 

DESCRIPTION 

Thesetroot program allows you to tailor the appearance of the background (root) window on aworkstation display running 
x. N ormally, you experiment with xsetroot until you find a personalized look that you like, then put the xsetroot command 
that produces it into your x startup file. If no options are specified, or if -def is specified, the window is reset to its default 
state. The -def option can be specified along with other options and only the nonspecified characteristics will be reset to the 
default state. 

Only one of the background color/tiling changing options (-solid, -gray, -grey, -bitmap, and -mod) may be specified at a 
time. 

OPTIONS 

The various options are as follows: 

-help 
-def 

-cursor cursorfiI e ma s kfi I e 


Print a usage message and exit. 

Reset unspecified attributes to the default values. (Restores the 
background to the familiar gray mesh and the cursor to the 
hollow x shape.) 

T his lets you change the poi nter cursor to whatever you want 
when the pointer cursor is outside of any window. Cursor and 
mask files are bitmaps (little pictures), and can be made with 
the bitmap(l) program. You probably want the mask file to be 
all black until you get used to theway maskswork. 



Parti: User Commands 



-cursor_name cursorname 


-bitmap f i I ename 


-mod x y 


-gray 
-grey 
-fg color 


-bg color 
-rv 


-solid color 
-name st ri ng 


-display di spi ay 

SEE ALSO 

X(l), xset(l), xrdb(l) 

AUTHOR 

M ark Lillibridge (MIT Project Athena) 


T his lets you change the poi nter cursor to one of thestandard 
cursors from the cursor font. Refer to Appendix B ofthex 
protocol for the names (except that the xc prefix is elided for 
thisoption). 

Use the bitmap specified in the file to set the window pattern. 
You can make your own bitmap files (little pictures) usingthe 
bitmap(l) program. T he entire background will be made up of 
repeated "tiles" of the bitmap. 

This is used if you want a pi aid-1 ike grid pattern on your 
screen, x and y are integers ranging from 1 to 16. Try the 
different combinations. Zero and negative numbers are taken 
asl. 

M ake the entire background gray. (Easier on the eyes.) 

M ake the entire background grey. 

Usecoi or as the foreground color. Foreground and back¬ 
ground colors are meaningful only in combination with 
-cursor, -bitmap, 01" -mod. 

Usecoi or as the background color. 

This exchanges theforeground and background colors 
N ormally theforeground color is black and the background 
color iswhite 

T his sets the background of the root wi ndow to the specified 
color. Thisoption isonly useful on color servers. 

Set the name of the root window to st r i ng. There is no default 
value. U sually a name is assigned to a window so that the 
window manager can use a text representation when the 
window isiconified. Thisoption isunused because you can't 
iconify the background. 

Specifies the server to connect to; seex(l). 
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xsm— x Session Manager 

SYNOPSIS 

xsm [-display display] [-session sessi onName] [-verbose] 

DESCRIPTION 

xsm is a session manager. A session is a group of applications, each of which has a particular state, xsm allows you to create 
arbitrary sessions. For example, you might have a light session, a development session, or an xterminai session. Each session 
can have its own set of applications. W ithin a session, you can perform a checkpoint to save application state, or a shutdown 
to save state and exit the session. W hen you log back in to the system, you can load a specific session, and you can delete 
sessions you no longer want to keep. 
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Some session managers simply allow you to manually specify a list of applications to be started in a session, xsm is more 
powerful because it lets you run applications and have them automatically become part of the session. On a simple level, xsm 
is useful because it gives you this ability to easily define which applications are in a session. The true power of xsm, however, 
can betaken advantage of when more and more applications learn to save and restore their state. 

OPTIONS 

-display di spi ay 
-session sessio n N a me 

-verbose 

SETUP 

. xsession FILE 

Using xsm requires a change to your .xsession file 

The last program executed by your .xsession file should be xsm. W ith this configuration, when the user chooses to shut 
down thesession using xsm, thesession will truly be over. 

Because the goal of thesession manager isto restart clientswhen logging into a session, your .xsession file, in general, should 
not directly start up applications Rather, theapplicationsshould be started within a session. When xsm shuts down the 
session, xsm will know to restart these applications. N ote, however, that there are some types of applications that are not 
"session aware'', xsm enables you to manually add these applications to your session. (See the subsection titled "Client List.") 

SM_SAVE_DIR ENVIRONMENT VARIABLE 

If the sm_save_dir environmentvariableisdefined, xsm will save all configuration files in this directory. Otherwise, they will 
be stored in the user's home directory. Session-aware applications are also encouraged to save their checkpoint files in the 
sm_save_dir directory, although theuser should not depend on thisconvention. 

DEFAULT STARTUP APPLICATIONS 

The first time xsm is started, it will need to locate a list of applicati ons to start up. For example this list might include a 
window manager, a session management proxy, and an xterm. xsm will first look for the file .xsmstartup in the user's home 
directory. If that file does not exist, it will look for the system.xsm file that was set up at installation time. N ote that xsm 
provides a failsafe option when theuser chooses a session to start up. The failsafe option simply loads the default 
applicati ons described above. 

Each line in the startup file should contain a command to start an application. A sample startup file might look this: 

<start of file> 
twm 

smproxy 

xterm 

<end of file> 

STARTING A SESSION 

When xsm starts up, it first checks to see if theuser previously saved any sessions If no saved sessions exist, xsm starts up a set 
of default applications (as described above in the subsection titled "Default Startup Applications”). If at least one session 
exists, aSession menu ispresented. The[ -session sessionName] option forces the specified session to beloaded, bypassing 
thesession menu. 

THESESSION MENU 

TheSession menu presents the user with a list of sessions to choose from. Theuser can change the currently selected session 
with the mouse, or by using the up and down arrows on the keyboard. N ote that sessions that are locked (that is, running on 
a different display) cannot beloaded or deleted. 


C auses xsm to connect to the specified X display. 

Causes xsm to load the specified session, bypassing the session 
menu. 

T urns on debugging information. 
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The following operations can be performed from the Session menu: 


Load Session 

Delete Session 

D efault/Fail Safe 

C ancel 

CONTROLLING A SESSION 


The following options are available from xsm'srnain window: 
Client List 


Pressing this button will load the currently selected session. 
Alternatively, hitting the Return key will also load the 
currently selected session, or the user can double-click a session 
from the list. 

Thisoperation will delete the currently selected session, along 
with all of the application checkpoint files associated with the 
session. After pressi ng this button, the user will be asked to 
press the button a second time in order to confirm the 
operation. 

xsm wil I start up a set of default applications (as descri bed 
earlier in the section titled "Default Startup Applications"). 

T his is useful when the user wantsto start a fresh session, or if 
the session configuration files were corrupted and the user 
wants a failsafe session. 

Pressing this button will cause xsm to exit. It can also be used 
to cancel a Delete Session operation. 


Pressing thisbutton brings up a window containing a list of all 
clients that are in the current session. For each client, the host 
machinethattheclient is running on is presented. Asclients 
are added and removed from thesession, thislist isupdated 
to reflect the changes. The user is able to control how these 
clients are restarted. 

By pressing the View Properties button, the user can view the 
session management properties associated with the currently 
selected client. 

By pressing the Clone button, theusercan startacopy of the 
selected application. 

By pressing the Kill Client button, theuser can removea client 
from thesession. By selecting a restart hint from the Restart 
H int menu, theuser can control the restarting of a client. T he 
following hints are available: 

■ The Restart If Running hint indicates that the client 
should be restarted in thenext session if it isconnected to 
thesession manager at the end of thecurrent session. 

■ The Restart Anyway hint indicatesthat theclient should 
be restarted in thenext session even if it exits before the 
current session is terminated. 

■ T he Restart I mmediately hint issimi lar to the Restart 
Anyway hint, but in addition, the client is meant to run 
continuously. If the client exits thesession manager will 
try to restart it in the current session. 

■ The Restart N ever hint indicates that the client should not 
be restarted in the next session. 


After xsm determines which session to load, it brings up its main window, then starts up all applications that are part of the 
session. The title bar for thesession manager's main window will contain the name of thesession that was loaded. 
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N otethat all X applications may not be session aware. 
Applications that are not session aware are ones that do not 
support theX Session M anagement Protocol or they cannot 
be detected by theSession M anagement Proxy. (Seethe 
subsection titled "The Proxy."), xsm allows the user to 
manually add such applications to thesession. The bottom of 
the Client List window contains a text entry field into which 
application commands can be typed. Each command should 
go on its own line. This information will be saved with the 
session at checkpoint or shutdown time. When thesession is 
restarted, xsm will restart these applications in addition to the 
regular session aware applications. Pressing the Done button 
removes the C lient List window. 

Session Log... TheSession Log window presents useful information about 

thesession. For example, when a session is restarted, all of the 
restart commands will be displayed in the log window. 

Checkpoint By performing a checkpoint, all applicationsthatarein the 

session are asked to save their state. N ot every application will 
save its complete state, but at a minimum, thesession manager 
isguaranteed that itwill receive the command required to 
restart theapplication (alongwith all command-lineoptions). 

A window manager participating in thesession should 
guarantee that the applications will comeback up with the 
samewindow configurations. 

If thesession being checkpointed was never assigned a name, 
theuserwill be required to specify a session name Otherwise, 
the user can perform the checkpoint using the current session 
name, or a new session name can be specified. If thesession 
namespecified already exists, theuserwill be given the 
opportunity to specify a different name or to overwrite the 
already existing session. N otethat a session that is locked can 
not be overwritten. 

When performing a checkpoint, the user must specify a save 
Type that informs the applications in thesession how much 
state they should save. 

The Local type indicates that the application should save 
enough information to restore the state as seen by the user. It 
should not affect the state as seen by other users. For example 
an editor would create a temporary file containing the contents 
of its editing buffer, the location of the cursor, and so on. 

The Global type indicates that theapplication should commit 
all of its data to permanent, globally accessible storage. For 
example, theeditor would simply savetheedited file. 

The Both type indicates that the application should do both of 
these. For example theeditor would save the edited file, then 
create a temporary file with information such as the location of 
the cursor, and so on. 

In addition to the save Type, the user must specify an interact 
Style. 

TheNone type indicates that the application should not 
i nteract with the user whi le savi ng state. 
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The Errors type indicates that the application may interact 
with the user only if an error condition arises. 

The Any type indicates that the application may interact with 
the user for any purpose N otethat xsm will only allow one 
application to interact with theuser at a time. 

After the checkpoint is completed, xsmwill, if necessary, 
display a window containing the list of applications that did 
not report a successful save of state. 

Shutdown A shutdown provides all of theoptionsfound in a checkpoint, 

but, in addition, can cause the session to exit. N otethat if the 
interaction style is Errors or Any, theuser may cancel the 
shutdown. T he user may also cancel the shutdown if any of 
the applications report an unsuccessful save of state. T he user 
may choose to shut down the session with or without 
performing a checkpoint. 

THE PROXY 

Because not all applications have been ported to support the X Session M anagement Protocol, a proxy service exists to enable 
"old" clients to work with the session manager. In order for the proxy to detect an application joining a session, one of the 
following must be true: 

■ The application maps a top-level window containing the wm_client_leader property. This property provides a pointer to 
the cl ient leader window that contains the wm_class, wm_name, wmjtommand, and wm_client_machine properties. 

or 

■ The application maps a top-level window that does not contain thewM_cLiENT_LEADER property. H owa/er, this top-level 
window contains the wm_class, wm_name, wm_command, and wm_client_machine properties. 

An application that supports the wm_save_yourself protocol will receive a wm_save_yourself cl ient message each time the 
session manager issues a checkpoint or shutdown. This allows the application to save state. If an application does not support 
the wm_save_yourself protocol, then theproxy will provide enough information to thesession manager to restart the 
application (using wm_command), but no state will be restored. 

REMOTE APPLICATIONS 

xsm requires a remote execution protocol in order to restart applications on remote machines. Currently, xsm supports the 
rstart protocol. In order to restart an application on remote machineX, machineX must haverstart installed. In the 
future, additional remote execution protocolsmay be supported. 

SEE ALSO 

smproxy(l), nstart(l) 

AUTHORS 

Ralph M or (X Consortium), Jordan Brown (Quarterdeck Office Systems) 

X Verson 11 Release6 
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xsmciient — X session manager tester 

SYNOPSIS 


xsmclient [ TBD ] 
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DESCRIPTION 

T he xsmciient program is used to test the session manager 

AUTHOR 

Ralph M or (X C onsortium) 

X Version 11 Release 6 
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xstdcmap— X standard colormap utility 

SYNOPSIS 

xstdcmap [-all] [-best] [-blue] [-default] [-delete map] [- display dis p I ay] 

[-gray] [-green] [-help] [-red] [-verbose] 

DESCRIPTION 

The xstdcmap utility can be used to selectively define standard colormap properties. It is intended to be run from a user's X 
startup script to create standard colormap definitions in order to facilitate sharing of scarce colormap resources among 
clients. W here at all possible, colormaps are created with read-only allocations. 


OPTIONS 

The following options may be used with xstdcmap: 

-all 


-best 

-blue 

-default 

-delete map 

-display display 

-gray 

-green 

-help 


-red 

-verbose 


This option indicates that all six standard colormap properties 
should be defined on each screen of the display. Not all screens 
will support visuals under which all six standard colormap 
properties are meaningful, xst-dcmap will determine the best 
allocations and visuals for the colormap properties of a screen. 
Any previously existing standard colormap properties will be 
replaced. 

This option indicates that the rgb_best_map should be defined. 
This option indicates that the rgb bluejiap should be defined. 
This option indicates that the rgb_default_map should be 
defined. 

This option specifies that a specific standard colormap 
property, or all such properties, should be removed, map may 
be One Of: default, best, red, green, blue, gray, Or all. 
Thisoption specifies the host and display to use; seex(l). 

This option indicates that the rgb_gray_map should be defined. 
Thisoption indicates that the rgb_green_map should be 
defined. 

This option indicates that a brief description of the command¬ 
line arguments should be printed on thestandard error. This 
will be done whenever an unhandled argument is given to 

xstdcmap. 

Thisoption indicates that the rgbred map should be defined. 
Thisoption indicates that xstdcmap should print logging 
information as it parses its input and defines the standard 
colormap properties. 
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ENVIRONMENT 

display To get default host and display number 

SEE ALSO 

X(l) 

AUTHOR 

Donna Converse (M IT X Consortium) 

X Version 11 Release 6 


xterm 

xterm—Terminal emulator forX 

SYNOPSIS 

xterm [—tool ki topti on ...] [-option ...] 

DESCRIPTION 

The xterm program is a terminal emulator for the X Window System. It provides DEC VT102- and T ektronix 4014- 
compatibleterminalsfor programs that can't use thewindow system directly. I f the underlying operating system supports 
terminal resizing capabilities (for example, thesiGwiNCH signal in systems derived from 4.3bsd), xterm will use the facilities to 
notify programs running in thewindow whenever it is resized. 

TheVT102 and T ektronix 4014 terminals all have their own windows so that you can edit text in one and look at graphics 
in the other at the same time. T o maintain the correct aspect ratio (height/width), T ektronix graphics will derestricted to the 
largest box with a 4014's aspect ratio that will fit in thewindow. This box is located in the upper-left area of thewindow. 

Although both windows may be displayed at the same time, one of them is considered the active window for receiving 
keyboard input and terminal output. Thisisthewindow thatcontainsthetext cursor. The active window can be chosen 
through escape sequences, theVT Options menu in the VT102 window, and theT ek Options menu in the 4014 window. 

EMULATIONS 

TheVT102 emulation isfairly complete, but does not support smooth scrolling, VT52 mode, theblinking character 
attribute nor the double-wide and double-size character sets. termcap( 5 ) entries that work with xterm include xterm, vti02, 
vtleo, and ansi, and xterm automatically searches the termcap file in this order for these entries and then sets the term and the 
termcap environment variables. 

M any of the special xterm features may be modified under program control through a set of escape sequences different from 
the standard VT 102 escape sequences. (See the "Xterm Control Sequences" document.) 

TheT ektronix 4014 emulation is also fairly good. It supports 12-bit graphics addressing, scaled to thewindow size. Four 
different font sizes and five different lines types are supported. There is no write-through or defocused mode support. The 
T ektronix text and graphics commands are recorded internally by xterm and may be written to a file by sending the copy 
escape sequence (or through theT ektronix menu, discussed later in this section). The name of the file will becoPYyy-MM- 
dd. hh: mm: ss, where yy, MM ,dd, hh, mm, and $ are the year, month, day, hour, minute, and second when thecoPY was 
performed (the file is created in the directory xterm i s started in, or the home directory for a login xterm). 

OTHER FEATURES 

xterm automatically highlightsthetext cursor when the pointer enters the window (selected) and unhighlights it when the 
pointer leaves the window (unselected). If thewindow is the focus window, then the text cursor is highlighted no matter 
where the pointer is. In VT102 mode, there are escape sequences to activate and deactivate an alternate screen buffer, which 
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isthe samesize asthe display area of the window. When activated, the current screen is saved and replaced with the alternate 
screen. Saving of lines scrolled off the top of the window is disabled until the normal screen is restored. Thetermcap(5) entry 
for xterm allows the visual editor vi(l) to switch to the alternate screen for editing and to restore the screen on exit. 

In either VT102 or Tektronix mode, there are escape sequences to change the name of the windows. See xterm Control 
Sequences for details. 


OPTIONS 


The xterm terminal emulator accepts all of the standard X T oolkit command-line options as well as the following (if the 
option begins with a + instead of a -, theoption is restored to its default value): 


-help 


-132 


-ah 


ah 

-b number 


-cb 

cb 

-cc character cl ass range: 
val ue [,... ] 


-cn 


cn 


-cr color 


cu 

-e program 
[ a r g u me n t s . . . ] 


-fb font 


This causes xterm to print out a verbose message describing its 
options. 

N ormally, the VT 102 deccolm escape sequence that switches 
between 80 and 132 column mode is ignored. Thisoption 
causes the deccolm escape sequence to be recognized, and the 
xterm window will resize appropriately. 

Thisoption indicates that xterm should always highlight the 
text cursor. By default, xterm will display a hollow text cursor 
whenever the focus is lost or the pointer leaves the window. 
Thisoption indicates that xterm should do text cursor 
highlighting based on focus 

This option specifies the size of the inner border (the distance 
between the outer edge of the characters and the wi ndow 
border) in pixels. The default is 2 . 

SetthevtlOO resource cutToBeginningOfLine to False. 

Set thevtlOO resource cutToBeginningOfLine tOTrue. 

This sets classes indicated by the given ranges to use in 
selecting by words. See the subsection "Character Classes." 
Thisoption indicates that newlines should not be cut in line¬ 
mode selections. 

Thisoption indicates that newlines should be cut in linemode 
selections. 

Thisoption specifies the color to use for text cursor. The 
default isto use the same foreground color that is used for text. 
This option indicates that xterm should work around a bug in 
the more(l) program that causes it to incorrectly display lines 
that are exactly the width of thewindow and are followed by a 
line begi nni ng with a tab (the leadi ng tabs are not displayed). 
Thisoption is so named because it was originally thought to 
be a bug in thecurses(3x) cursor motion package. 

This option indicates that xterm should not work around the 
more(3x) bug mentioned in the preceding paragraph. 
Thisoption specifies the program (and its command-line 
arguments) to be run in the xterm window. It also sets the 
window title and icon nameto bethebasenameof the 
program being executed if neither -t nor-n are given on 
the command line. This must be the last option on the 
command line. 

This option specifies a font to be used when displaying bold 
text. This font must be the same height and width asthe 
normal font. If only one of the normal or bold fonts is 



702 


Parti: U ser Commands 


-im 

+im 


i 


-Is 


Is 


-mb 


mb 

-mcmi I I i seconds 


-ms color 


-nb number 


-rw 


rw 


specified, it will be used as the normal font and the bold font 
will be produced by overstriking this font. The default is to do 
overstriking of the normal font. 

T urn on theuseinsertMode resource. 

Turn off theuseinsertMode resource. 

This option indicates that xterm should do jump scrolling. 

N ormally, text is scrolled one line at a time thisoption allows 
xterm to move multiple lines at a time so that it doesn't fall as 
far behind. Its use is strongly recommended because it makes 
xterm much faster when scanning through large amounts of 
text. The VT100 escape sequences for enabling and disabling 
smooth scroll as well astheVT Optionsmenu can beusedto 
turn thisfeatureon or off. 

Thisoption indicates that xterm should not do jump scrolling. 
Thisoption indicates that the shell that is started in the xterm 
window will bea login shell (that is, the first character of 
arg v [ 0 ] will beadash, indicatingto the shell that it should 
read theuser's .login or .profile). 

Thisoption indicates that the shell that is started should not 
bea login shell (that is, itwill bea normal subshell). 
Thisoption indicates that xterm should ringamargin bell 
when the user types near the right end of aline. Thisoption 
can be turned on and off from the VT Optionsmenu. 
Thisoption indicates that margin bell should not be rung. 
Thisoption specifies the maximum timebetween multiclick 
selections. 

Thisoption specifies the color to be used for the pointer 
cursor. The default is to use the foreground color. 

This option specifies the number of characters from the right 
end of a line at which themargin bell, if enabled, will ring. 
The default is 10 . 

This option indicates that reverse-wraparound should be 
allowed. This allows the cursor to back up from the leftmost 
column of one line to the rightmost column of the previous 
line. This is very useful for editing long shell command lines 
and is encouraged. Thisoption can be turned on and off from 
theVT Optionsmenu. 

This option indicates that reverse-wraparound should not be 
allowed. 

Thisoption indicates that auto-wraparound should be 
allowed. This allows the cursor to automatically wrap to the 
beginning of the next linewhen it isat the rightmost position 
of a line and text is output. 

Thisoption indicates that auto-wraparound should not be 
allowed. 

Thisoption indicates that xterm may scroll asynchronously, 
meaning that the screen does not have to be kept completely 
up to date while scrolling. This allows xterm to run faster when 
network latencies are very high and istypically useful when 
running across a very large Internet or many gateways. 
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S 


-sb 


sb 


-sf 


sf 


si 


-sk 


sk 


-si number 


t 

-tm st ri ng 


-tn name 


-ut 


ut 


-vb 


vb 


-wf 


Thisoption indicates that xterm should scroll synchronously. 
This option indicates that some number of lines that are 
scrolled off the top of the window should be saved and that a 
scrollbar should bedisplayed so that those lines can be viewed. 
Thisoption may be turned on and off from theVT Options 
menu. 

Thisoption indicates that a scrollbar should not bedisplayed. 
Thisoption indicates that Sun Function Key escape codes 
should be generated for function keys. 

Thisoption indicates that the standard escape codes should be 
generated for function keys. 

Thisoption indicates that output to a window should not 
automatically reposition thescreen to the bottom of the 
scrolling region. Thisoption can be turned on and off from 
theVT Options menu. 

Thisoption indicates that output to a window should cause it 
to scroll to the bottom. 

Thisoption indicates that pressing a key while using the 
scrollbar to review previous lines of text should cause the 
window to be repositioned automatically in the normal 
position at the bottom of thescroll region. 

This option indicates that pressi ng a key while usi ng the 
scrollbar should not cause the window to be repositioned. 
Thisoption specifies the number of lines to save that have 
been scrolled off thetop of thescreen. The default is 64. 
Thisoption indicates that xterm should start in Tektronix 
mode, rather than in VT102 mode. Switching between the 
two windows is done using theO ptionsmenus 
Thisoption indicates that xterm should start in VT102 mode. 
Thisoption specifies a series of terminal setting keywords 
followed by the characters that should be bound to those 
functions, similar to thestty program. Allowable keywords 
include intr, quit, erase, kill, eof, eol, swtch, start, stop, 
brk, susp, dsusp, rprnt, flush, weras, and lnext. Control 
characters may be specified as -char (for example, *c or -u) and 
-? may beused to indicate delete. 

Thisoption specifies the name of theterminal type to beset in 
the term environment variable. T his terminal type must exist 
in the termcap(5) database and should haven# and co# entries. 
Thisoption indicates that xterm shouldn't write a record into 
the system log file /etc/utmp. 

This option indicates that xterm should write a record into the 
system log file /etc/utmp. 

Thisoption indicates that a visual bell is preferred over an 
audible one. Instead of ringing theterminal bell whenevera 
CtrlTG is received, thewindow will be flashed. 

Thisoption indicates that a visual bell should not be used. 
This option indicates that xterm should wait for the window to 
bemapped the first time before starti ng thesubprocess so that 
theinitial terminal size settings and environment variables are 
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correct. It is the appl ication's responsibility to catch subse¬ 
quent terminal size changes. 

wf 

This option indicates that xterm show not wait before starting 
the subprocess. 

-C 

Thisoption indicates that thiswindow should receive console 
output. This is not supported on all systems. T o obtain 
console output, you must betheowner of the console device, 
and you must have read and write permission for it. If you are 
running x under xdm on the console screen, you may need to 
have the session startup and reset programs explicitly change 
the ownership of the console device in order to get this option 
to work. 

-Seen 

Thisoption specifies the last two letters of the name of a 
pseudo-terminal to use in slave mode, plus the number of the 
inherited file descriptor. Theoption isparsed "%c%c%d". This 
allows xterm to be used as an input and output channel for an 
existing program and issometimesused in specialized 
applications. 

The following command-line arguments are provided for compatibility with older versions. They may not be supported in 
the next release as theX T oolkit provides standard optionsthat accomplish thesametask. 

%geom 

Thisoption specifies the preferred size and position of the 

Tektronix window. It is shorthand for specifyi ng the 


*tekGeometry resource. 

geom 

Thisoption specifies the preferred position of the icon 
wi ndow. 11 is shorthand for specifyi ng the *iconGeometry 


resource. 

-T string 

Thisoption specifies the title for xterm's windows. It is 
equivalent to -title. 

-n string 

Thisoption specifies the icon name for xterm's windows. Itis 
shorthand for specifying the *iconName resource. N ote that this 
is not the same as the toolkit option -name (see below). The 
default icon nameistheapplication name. 

-r 

Thisoption indicates that reverse video should be simulated by 
swapping the foreground and background colors. It is 
equivalent to -rv. 

-w number 

Thisoption specifies the width in pixels of the border 
surrounding the window. It is equivalent to -borderwidth or 

-bw. 

T he following standard X T oolkit command-line arguments are commonly used with xterm: 

-bg color 

Thisoption specifies the color to use for the background of the 
window. The default iswhite. 

-bd color 

Thisoption specifies the color to use for the border of the 
window. T he default is black. 

-bw number 

Thisoption specifies the width in pixels of the border 
surrounding the window. 

-fg color 

Thisoption specifies the color to use for displaying text. The 
default is black. 

-fn font 

Thisoption specifies the font to be used for displaying normal 
text. The default is fixed. 
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-name name 


-title st ri ng 


-geometry geomet r y 

-display display 
-xrm r esour cest ri ng 


-iconic 


Thisoption specifies theapplicati on name under which 
resources are to be obtained, rather than the default executable 
filename. Nameshould not contain . or* characters. 
Thisoption specifies thewindow title string, which maybe 
displayed by window managers if the user so chooses. The 
default title is the command line specified after the -e option, 
if any; otherwise the application name. 

Thisoption indicates that reverse video should be simulated by 
swapping the foreground and background colors 
Thisoption specifies the preferred size and position of the 
VT102 window; seex(l). 

Thisoption specifies theX server to contact; seex(l). 
Thisoption specifies a resource string to be used. This is 
especially useful for setting resources that do not have separate 
command-lineoptions. 

Thisoption indicates that xterm should ask thewindow 
manager to start it as an icon rather than as the normal 
window. 


RESOURCES 


The program understands all of the coreX T oolkit resource names and classes as well as the following: 


iconGeometry (class IconGeometry) 

iconName (class IconName) 
termName (class TermName) 

title (class Title) 

ttyModes (class TtyModes) 


uselnsertMode 
(class UselnsertMode) 

utmplnhibit (class Utmplnhibit) 

sunFunctionKeys 
(class SunFunctionKeys) 

waitForMap (class WaitForMap) 


Specifies the preferred size and position of the application 
when iconified. It is not necessarily obeyed by ail window 
managers. 

Specifies the icon name. The default istheapplication name. 
Specifies the terminal typenameto beset in theTERM 
environment vari able. 

Specifies a string that may beused by thewindow manager 
when displayingthisapplication. 

Specifies a string containing terminal setting keywords and the 
characters to which they may be bound. Allowable keywords 
include intr, quit, erase, kill, eof, eol, swtch, start, stop, 
brk, susp, dsusp, rprnt, flush, weras, and lnext. Control 
characters may be specified as "char (for example, "c or "u) and 
•? may beused to i ndicate delete. This is very useful for 
overriding the default terminal settings without having to do 
an stty every time an xterm is started. 

Force use of insert mode by adding appropriate entries to the 
termcap environment variable This is useful if the system 
termcap is broken. T he default is False. 

Specifies whether or not xterm should try to record the user's 
terminal in /etc/utmp. 

Specifies whether or not Sun Function Key escape codes 
should be generated for function keys instead of standard 
escape sequences. 

Specifies whether or not xterm should wait for the initial 
window map before starting the subprocess. The default is 
false. 
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The following resources are specified as part of thevtlOO widget (class vti 00 ): 


allowSendEvents 
(class AllowSendEvents) 


alwaysHighlight 
(class AlwaysHighlight) 


appcursorDefault 
(class AppcursorDefault) 
appkeypadDefault 
(class AppkeypadDefault) 
autoWrap (class AutoWrap) 

bellSuppressTime 
(class BellSuppressTime) 


boldFont (class BoldFont) 

cl32 (class C132) 

cutNewline 
(class CutNewline) 

cutToBeginningOfLine 
(class CutToBeginningOfLine) 

charClass (class CharClass) 


curses (class Curses) 


background 
(class Background) 
foreground 
(class Foreground) 


cursorColor 
(class Foreground) 
eightBitlnput 
(class EightBitlnput) 


Specifies whether or not synthetic key and button 
events (generated usi ng the x protocol sendEvent request) 
should be interpreted or discarded. The default is False, 
meaning they arediscarded. N otethat allowing such a/ents 
creates a very large security hole. 

Specifies whether or not xterm should alwaysdisplay 
a highlighted text cursor. By default, a hollow text cursor is 
displayed whenever the pointer moves out of the window or 
thewindow loses theinput focus. 

If true, the cursor keys are initially in application mode. 

T he default is false. 

If true, thekeypad keysareinitially in application mode. 

T he default is false. 

Specifies whether or not auto-wraparound should be enabled. 
T he default is true. 

N umber of milliseconds after a bell command is sent during 
which additional bells will be suppressed. D efault is 200 . If set 
non-zero, additional bells will also be suppressed until the 
server reports that processing of the first bell has been com¬ 
pleted; this feature is most useful with the visible bell. 

Specifies the name of the bold font to use instead of 
overstriking. 

Specifies whether or nottheVT102 deccolm escape sequence 
should be honored. The default isfaise. 

If false, triple-clicking to select a line does not 

include theNewiine attheend of theline. If true, the Newline 

is selected. T he default is true. 

If false, triple-clicking to select a line selects only from 
the current word forward. If true, the entire line is selected. 

T he default is true. 

Specifies comma-separated lists of character class bindings of 
the form [ low-] high: value. These are used in determining 
which sets of characters should be treated the same when 
doing cut and paste. Seethesection on specifying character 
classes. 

Specifies whether or not the last column buginmore(l) should 
be worked around. See the -cu option for detai Is. T he default 
is false. 

Specifies the color to use for the background of thewindow. 
The default iswhite. 

Specifies the color to usefordisplayingtextin thewindow. 
Setting the class name instead of the instance name is an easy 
way to have everything that would normally appear in the text 
color change color. The default is black. 

Specifies the color to use for the text cursor. The 
default is black. 

If true, metacharacters input from the keyboard are presented 
as a single character with the eighth bit turned on. If false, 
metacharacters are converted into a two-character sequence 
with the character itself preceded by ESC. The default istrue. 
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eightBitOutput 
(class EightBitOutput) 

font (class Font) 
fontl (class Fontl) 
font2 (class Font2) 
font3 (class Font3) 
font4 (class Font4) 
fonts (class Fonts) 
font6 (class Font6) 
geometry (class Geometry) 

hpLowerleftBugCompat 
(class HpLowerleftBugCompat) 


internalBorder 

(class BorderWidth) 

jumpScroll 

(class JumpScroll) 

loginShell 

(class LoginShell) 

marginBell 

(class MarginBell) 

multiClickTime 

(class MultiClickTime) 

multiScroll 

(class MultiScroll) 

nMarginBell (class Column) 

pointerColor 

(class Foreground) 

pointerColorBackground 

(class Background) 

pointerShape 

(class Cursor) 

resizeGravity 

(class ResizeGravity) 


reverseVideo 
(class ReverseVideo) 


Specifies whether or not eight-bit characters sent from the 
host should be accepted as is or stripped when printed. The 
default istrue. 

Specifies the name of the normal font. The default istixed. 
Specifi es the name of the first alternative font. 

Specifies the name of the second alternative font. 

Specifi es the name of the third alternative font. 

Specifi es the name of the fourth alternative font. 

Specifi es the name of the fifth alternative font. 

Specifi es the name of the sixth alternative font. 

Specifies the preferred size and position of theVT102 
window. 

Specifies whether to work around a bug in H P'sxdb, which 
ignores tenmcap and always sends ESC F to move to the lower- 
left corner, true causes xterm to interpret ESC F as a request 
to move to the lower-left corner of the screen. T he default is 
false. 

Specifies the number of pixels between the characters and the 
window border. The default is 2 . 

Specifies whether or not jump scroll should be used. The 
default istrue. 

Specifies whether or not the shell to be run in thewindow 
should be started as a login shell. The default istaise. 
Specifies whether or not the bel I should be run when theuser 
types near the right margin. T he default is false. 

Specifies the maximum time in milliseconds between 
multiclick select events. The default is250 milliseconds. 
Specifies whether or not scrolling should be done asynchro¬ 
nously. The default iSfalse. 

Specifi es the number of characters from the right margi n at 
which the margin bell should be rung, when enabled. 

Specifies the foreground color of the pointer. T he default is 

XtDefaultForeground. 

Specifies the background color of the pointer. The default is 

XtDefaultBackg round. 

Specifies the name of the shape of the pointer. T he default is 

xterm. 

Affects the behavior when thewindow i s resi zed to be taller or 
shorter. Northwest specifies that the top lineof text on the 
screen stay fixed. If thewindow is made shorter, lines are 
dropped from the bottom; if thewindow ismade taller, blank 
lines are added at the bottom. This is compatible with the 
behavior in R4. southwest (the default) specifies that the 
bottom lineof text on thescreen stay fixed. If thewindow is 
made taller, additional saved lines will be scrolled down onto 
thescreen; ifthewindow is made shorter, lines will be scrolled 
off the top of thescreen, and the top saved lines will be 
dropped. 

Specifies whether reverse video should be simulated. The 
default istaise. 
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reverseWrap 

(class ReverseWrap) 

saveLines 

(class SaveLines) 

scrollBar 

(class ScrollBar) 

scrollTtyOutput 

(class ScrollCond) 

scrollKey 
(class ScrollCond) 

scrollLines 
(class ScrollLines) 
signallnhibit 
(class Signallnhibit) 

tekGeometry 

(class Geometry) 

teklnhibit 

(class Teklnhibit) 

tekSmall (class TekSmall) 


tekStartup 
(class TekStartup) 
titelnhibit 
(class Titelnhibit) 


translations 
(class Translations) 

visualBell 
(class VisualBell) 

Thefollowing resources are specified as part of thetek4@i4 

width (class Width) 

height (class Height) 

fontLarge (class Font) 

font2 (class Font) 

font3 (class Font) 

fontSmall (class Font) 

initialFont (class InitialFont) 


Specifies whether or not reverse-wraparound should be 
enabled. The default is false. 

Specifi es the number of lines to save beyond the top of the 
screen when a scrollbar isturned on. The default is 64. 

Specifies whether or not the scrollbar should be displayed. 

The default isfaise. 

Specifies whether or not output to theterminal should 
automatically cause the scrollbar to go to the bottom of the 
scrolling region. The default istrue. 

Specifies whether or not pressing a key should automatically 
cause thescrollbar to go to the bottom of the scrolling region. 
The default isfaise. 

Specifies the number of lines that the scroii-back and scroll- 
forw actions should use as a default. The default value is i. 
Specifies whether or not the entries in theM ain Options menu 
for sending signals to xterm should be disallowed. The default 
is false. 

Specifies the preferred size and position of theT ektronix 
window. 

Specifies whether or not the escape sequence to enter 
T ektronix mode should be ignored. The default is false. 
Specifies whether or not theT ektronix mode window should 
start in its smallest size if no explicit geometry is given. This is 
useful when running xterm on displays with small screens. The 
default isfaise. 

Specifies whether or not xterm should start up in T ektronix 
mode. The default isfaise. 

Specifies whether or not xterm should remove ti and te 
termcap entries (used to switch between alternate screens on 
startup of many screen-oriented programs) from the termcap 
string. If set, xterm also ignores the escape sequence to switch 
to the alternate screen. 

Specifies the key and button bindings for menus, selections, 
"programmed strings," and SO On. See the "ACT 10 N S” 
subsection, later in thissection. 

Specifies whether or not a visible bell (that is, flashing) should 
beused instead of an audible bell when Control-G isreceived. 
The default isfaise. 

idget (class Tek40 14 ): 

Specifies the width of theT ektronix window in pixels. 

Specifies the height of theTektronixwindow in pixels. 

Specifi esthelarge font to usein theT ektronix window. 
Specifies font number 2 to usein theT ektronix window. 
Specifies font number 3 to usein theT ektronix window. 
Specifies the small font to usein theT ektronix window. 
Specifies which of the four Tektronix fonts to use initially. 

V alues are the same as for the set - tek - text acti on. The default 
is large. 
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ginTerminator Specifies what character(s) should follow a GIN 

(class GinTerminator) report or status report. T he possibilities are none, which sends 

no terminating characters, cRoniy, which sends cr, and cr&eot, 
which sends both cr and eot. The default is none 


The resources that may be specified for the various menus are described in the documentation for the Athena simpieMenu 
widget. The name and classes of the entries in each of the menus are listed next. 


ThemainMenu has the following entries: 

securekbd (class SmeBSB) 
allowsends (class SmeBSB) 
redraw (class SmeBSB) 
linel (class SmeLine) 
suspend (class SmeBSB) 

continue (class SmeBSB) 

interrupt (class SmeBSB) 
hangup (class SmeBSB) 
terminate (class SmeBSB) 
kill (class SmeBSB) 
line2 (class SmeLine) 
quit (class SmeBSB) 


This entry invokes the secured action. 

T his entry invokes the aiiow-send-events(toggie) action. 
This entry invokes the redraw) > action. 

This is a separator. 

This entry invokes thesend-signai(tstp) action on systems 
that support job control. 

This entry invokes thesend-signai(cont) action on systems 
that support job control. 

This entry invokes thesend-signai(int) action. 

This entry invokes thesend-signai(hup) action. 

This entry invokes thesend-signai(term) action. 

This entry invokes thesend-signai(kiii) action. 

This is a separator. 

T his entry invokes the quit o action. 


T he vtMenu has the following entries: 
scrollbar (class SmeBSB) 
jumpscroll (class SmeBSB) 
reversevideo (class SmeBSB) 
autowrap (class SmeBSB) 
reversewrap (class SmeBSB) 
autolinefeed (class SmeBSB) 
appcursor (class SmeBSB) 
appkeypad (class SmeBSB) 
scrollkey (class SmeBSB) 
scrollttyoutput 
(class SmeBSB) 
allow132 (class SmeBSB) 
cursesemul (class SmeBSB) 
visualbell (class SmeBSB) 
marginbell (class SmeBSB) 
altscreen (class SmeBSB) 
linel (class SmeLine) 
softreset (class SmeBSB) 
hardreset (class SmeBSB) 
clearsavedlines (class SmeBSB)" 
line2 (class SmeLine) 
tekshow (class SmeBSB) 
tekmode (class SmeBSB) 


This entry invokes theset-scroiibar(toggie) action. 

This entry invokes theset-jumpscroii(toggie) action. 
This entry invokes the set - reverse-video (toggle) action. 
This entry invokes theset-autowrap(toggie) action. 

This entry invokes the set - reversewrap (toggle) action. 
This entry invokes the set -autolinef eed(toggle) action. 
This entry invokes theset-appcursor(toggie) action. 

This entry invokes theset-appkeypad(toggie) action. 

This entry invokes the set-scroll-on-key (toggle) action. 
T his entry invokes the set-scroll-on-tty-output(toggle) 
action. 

This entry invokes theset-aiiowi32(toggie) action. 

This entry invokes theset-cursesemui(toggie) action. 
This entry invokes theset-visuaibeii(toggie) action. 
This entry invokes theset-marginbell(toggle) action. 
This entry is currently disabled. 

This is a separator. 

This entry invokes the soft-reset o action. 

This entry invokes the hard-reset o action. 

This entry invokes the ciear-saved-nneso action. 

This is a separator. 

This entry i nvokes the set -visionity(tek, toggle) action. 
This entry invokes the set-terminal-type(tek) action. 




Parti: User Commands 


vthide (class SmeBSB) 

ThetontMenu has the following entries: 

fontdefault (class SmeBSB) 

fontl (class SmeBSB) 

font2 (class SmeBSB) 

font3 (class SmeBSB) 

font4 (class SmeBSB) 

font5 (class SmeBSB) 

font6 (class SmeBSB) 

fontescape (class SmeBSB) 

fontsel (class SmeBSB) 

ThetekMenu has the following entries: 

tektextlarge (class SmeBSB) 

tektext2 (class SmeBSB) 

tektext3 (class SmeBSB) 

tektextsmall (class SmeBSB) 

linel (class SmeLine) 

tekpage (class SmeBSB) 

tekreset (class SmeBSB) 

tekcopy (class SmeBSB) 

line2 (class SmeLine) 

vtshow (class SmeBSB) 

vtmode (class SmeBSB) 

tekhide (class SmeBSB) 


This entry invokes theset-visibmty(vt, off) action. 


This entry invokes theset-vt-font(d) action. 
This entry invokes theset-vt-font(i) action. 
This entry invokes the set -vt-font( 2 ) action. 
This entry invokes theset-vt-font(3) action. 
This entry invokes theset-vt-font(4) action. 
This entry invokes theset-vt-font(5) action. 
This entry invokes theset-vt-font(6) action. 
This entry invokes theset-vt-font(e) action. 
This entry invokes theset-vt-font(s) action. 


This entry invokes theset-tek-text(i) action. 

This entry invokes theset-tek-text( 2 ) action. 

This entry invokes theset-tek-text(3) action. 

This entry invokes theset-tek-text(s) action. 

This is a separator. 

This entry invokes thetek-pageo action. 

This entry invokes the tek-reset o action. 

This entry invokes the tek-copy() action. 

This is a separator. 

This entry invokestheset-visibiiity(vt, toggle) action. 
This entry invokes theset-terminai-type(vt) action. 

This entry invokes the set-visibility (tek, toggle) action. 


The following resources are useful when specified for the Athena Scrollbar widget: 


thickness (class Thickness) 
background (class Background) 
foreground (class Foreground) 


Specifies the width in pixels of the scrollbar. 

Specifies the color to use for the background of the scrollbar. 
Specifies the color to use for the foreground of the scrollbar. 
The "thumb" of the scrollbar is a simple checkerboard pattern 
alternating pixelsfor foreground and background color. 


POINTER USAGE 

Once the VT102 window is created, xterm allows you to select text and copy it within the same or other windows. 

The selection functions are invoked when the pointer buttons are used with no modifiers, and when they are used with the 
Shift key. The assignment of the functions described in this subsection to keys and buttons may be changed through the 
resource database; see the "Actions” subsection later in this section. 

Pointer button one (usually left) is used to save text into the cut buffer. M ove the cursor to the beginning of the text, and 
then hold thebutton down while moving the cursor to theend of theregion and releasing the button. The selected text is 
highlighted and issaved in the global cut buffer and made the primary selection when thebutton is released. Double-clicking 
selects by words. T riple-clicking selects by lines. Quadruple-clicking goes back to characters, and so on. M ultiple-click is 
determined by thetimefrom button up to button down, so you can change the selection unit in the middle of a selection. If 
the key/button bindings specify that an X selection is to be made xterm will leave the selected text highlighted for as long as 
it isthe selection owner. 
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Pointer button two (usually middle) "types" (pastes) thetextfrom thepRiMARY selection, if any, otherwise from thecut 
buffer, inserting it askeyboard input. 

Pointer button three (usually right) extends the current selection. (Without loss of generality, you can swap "right" and "left” 
everywhere in the rest of this paragraph.) If pressed while closer to the right edge of the selection than the left, it extends/ 
contracts the right edge of the selection. If you contract the selection past the left edge of the selection, xterm assumes you 
really meant the left edge, restores theoriginal selection, then extends/contracts the left edge ofthe selection. Extension starts 
in the selection unit mode that the last selection or extension was performed in; you can multiple-click to cycle through 
them. 

By cutting and pasting pieces of text without trailing new lines, you can take text from several places in different windows 
and form a command to the shell, for example, or take output from a program and insert it into your favorite editor. Since 
thecut buffer is globally shared among different applications, you should regard it as a file whose contents you know. The 
terminal emulator and other text programs should be treating it as if it were a text file; that is, the text is delimited by new 
lines. 

T he scroll region di splays the position and amount of text currently showing in the window (highlighted) relative to the 
amount of text actually saved. As more text is saved (up to the maximum), the size of the highlighted area decreases. 

Clicking button onewith the pointer in the scroll region moves the adjacent lineto thetop of the display window. 

Clicking button three moves the top line of the display window down to the pointer position. 

Clicking button two moves the display to a position in the saved text that corresponds to the pointer's position in the 
scrollbar. 

UnliketheVT102 window, theTektronix window does not allow the copying of text. It does allow Tektronix GIN mode, 
and in this mode the cursor will change from an arrow to across. Pressing any key will send that key and the current 
coordinate of the cross cursor. Pressing button one, two, or three will return the letters 1 , m, and r, respectively. If the Shift 
key is pressed when a pointer button is pressed, the corresponding uppercase letter is sent. T o distinguish a pointer button 
from a key, the high bit of the character is set (but this is bit is normally stripped unless the terminal mode is RAW; see 
tty(4) for details). 

MENUS 

xterm has four menus: mainMenu, vtMenu, fontMenu, and tekMenu. Each menu pops up under the correct combinations of key 
and button presses. M ost menus are divided into two sections, separated by a horizontal line. Thetop portion contains 
various modes that can be altered. A check mark appears next to a mode that is currently active. Selecting one of these modes 
toggles its state. The bottom portion of the menu consists of command entries; selecting oneof these performs theindicated 
function. 

The xterm menu pops up when the Control key and pointer button one are pressed in a window. The mainMenu contains 
itemsthat apply to both the VT102 and T ektronix windows. The Secure Keyboard mode is used when typing in passwords 
or other sensitive data in an unsecured environment. (See the "SEC U R IT Y" subsection.) Notable entries in the command 
section of the menu are the Continue, Suspend, Interrupt, H angup, T erminate, and Kill, which send thesiGCONT, sigtstp, 
sigint, sighup, sigterm, and sigkill signals, respectively, to the process group of the process running under xterm (usually 
the shell). The Continue fundi on is especially useful if the user has accidentally typed CTRL-Z, suspending the process. 

The vtMenu sets various modes in the VT 102 emulation, and is popped up when the Control key and pointer button two are 
pressed in the VT 102 window. In the command section of this menu, the Soft Reset entry will reset scroll regions. This can 
be convenient when some program has left the scroll regions set incorrectly (often a problem when using VM S or TO PS-20). 
The Full Reset entry will clear the screen, reset tabs to every eight columns, and reset the terminal modes (such as wrap and 
smooth scroll) to their initial states just after xterm has finished processing the command-line options. 

The fontMenu sets the font used in the VT 102 window. In addition to the default font and a number of alternatives that are 
set with resources, the menu offers the font last specified by the Set Font escape sequence (see the document "Xterm Control 
Sequences") and the current selection as a font name (if thepRiMARY selection is owned). 
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ThetekMenu sets various modes in theT ektronix emulation, and is popped up when the Control key and pointer button two 
are pressed in theT ektronix window. The current font size is checked in the M odes section of the menu. The page entry in 
the Command section clears theT ektronix window. 

SECURITY 

X environments differ in their security consciousness. M ost servers, run under xdm, are capable of using a "magic cookie” 
authorization scheme that can provide a reasonable level of security for many people. If your server is only using a host-based 
mechanism to control access to the server (see xhost(l)), then if you enable access for a host and other users are also 
permitted to run clients on that same host, there is every possibility that someone can run an application that will use the 
basic services of thex protocol to snoop on your activities, potentially capturing a transcript of everything you type at the 
keyboard. This is of particular concern when you want to type in a password or other sensitive data. The best solution to this 
problem is to use a better authorization mechanism that host-based control, but a simple mechanism exists for protecting 
keyboard input in xterm. 

The xterm menu (see"M enus,” earlier in this section) contains a secure Keyboard entry which, when enabled, ensures that all 
keyboard input is directed only to xterm (using theGrabKeyboard protocol request). When an application prompts you for a 
password (or other sensitive data), you can enable secure Keyboard using the menu, type in the data, and then disable secure 
Keyboard using the menu again. Only one X client at a time can secure the keyboard, so when you attempt to enable secure 
Keyboard, it may fail. In thiscase, the bell will sound. If thesecure Keyboard succeeds, the foreground and background colors 
will be exchanged (as if you selected the Reverse Video entry in the M odes menu); they will be exchanged again when you 
exit secure mode. If the colors do not switch, then you should be very suspicious that you are being spoofed. If the applica¬ 
tion you are running displays a prompt before asking for the password, it is safest to enter secure mode before the prompt 
gets displayed, and to make sure that the prompt gets displayed correctly (in the new colors), to minimize the probability of 
spoofing. You can also bring up the menu again and make sure that a check mark appears next to theentry. 

Secure Keyboard mode will bedisabled automatically if your xterm window becomes icon ified (or otherwise unmapped), or 
if you startup a reparenting window manager (that places atitle bar or other decoration around thewindow) while in Secure 
Keyboard mode. (This is a feature of thex protocol that isn't easily overcome.) When this happens, the foreground and 
background colors will be switched back and thebell will sound in warning. 

CHARACTER CLASSES 

Clickingthemiddlemouse button twice in rapid succession will cause all charactersof thesameclass(for example, letters, 
whitespace, punctuation) to be selected. Si nee different people have different preferences for what should be selected (for 
example, should filenames be selected as a whole or only the separate subnames?), the default mapping can be overridden 
through the use of the charciass (class charciass) resource 

This resource is a series of comma-separated range: vai ue pairs. The range is either a single number or low-high in the range 
of 0 to 127, corresponding to theASCII code for the character or characters to beset. The value is arbitrary, although the 
default table uses the character number of the first character occurring in the set. 

The default table is 

static int charClass[128] = { 

/* NUL SOH STX ETX EOT ENQ ACK BEL */ 

32, 1, 1, 1, 1, 1, 1, 1, 

/* BS HT NL VT NP CR SO SI */ 

1, 32, 1, 1, 1, 1, 1, 1, 

/* DLE DC1 DC2 DC3 DC4 NAK SYN ETB */ 

1, 1, 1, 1, 1 , 1, 1, 1, 

/* CAN EM SUB ESC FS GS RS US */ 

1, 1, 1, 1, 1 , 1, 1, 1, 


/*SP 

!"#$%& 1 ' 

k l 





32, 

33, 

34, 

35, 

36, 

37, 

38, 

39 

/*() 

*+,- 


1 





40, 

41, 

42, 

43, 

44, 

45, 

46, 

47 

/*0 

1 2 

3 4 

5 6 

7 * 

/ 
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48, 48, 48, 

48, 

48, 

48, 

48, 

48 

/*8 9 :;< = 

= > ?*, 

1 




48, 48, 58, 

59, 

60, 

61, 

62, 

63 

/*@ABC D E 

F G*, 

1 




64, 48, 48, 

48, 

48, 

48, 

48, 

48 

/* H I J K 

L M N 0 

*/ 



48, 48, 48, 

48, 

48, 

48, 

48, 

48 

/*P QR S T 

UVW*/ 




48, 48, 48, 

48, 

48, 

48, 

48, 

48 

/*xy z [\r 

*/ 





48, 48, 48, 

91, 

92, 

93, 

94, 

48 

/*'ab c d e fg ’ 

7 




96, 48, 48, 

48, 

48, 

48, 

48, 

48 

/*h ijklm n 

1 0 *, 

1 




48, 48, 48, 

48, 

48, 

48, 

48, 

48 

/*p q rs tu 

1 v w 

*/ 




48, 48, 48, 

48, 

48, 

48, 

48, 

48 


/*x y zf jg' DEL */ 

48, 48, 48, 123, 124, 125, 126, 1}; 

For example, the string 33:48,37:48,45-47:48,64:48 indicates that the exclamation mark, percent sign, dash, period, slash, 
and ampersand characters should be treated the same way as characters and numbers. This is useful for cutting and pasting 
electronic mailing addresses and filenames. 


ACTIONS 


It is possible to rebind keys (or sequences of keys) to arbitrary strings for input by changing the translations for the vtioa or 
tek40i4 widgets. Changing the translations for events other than key and button events is not expected, and will cause 
unpredictable behavior. T he following actions are provided for using within the vtioo or tek40i 4 translations resources: 


bell([per cent ]) 
ignore)) 
insert)) 

insert-seven-bit)) 
insert-eight-bit() 


insert-selection 
(sour cename [, ... ]) 


keymap(name) 


popup-menu(menuname) 


secure)) 


Thisaction rings the keyboard bell at the specified percentage 
above or below the base volume. 

Thisaction ignores the event but checks for special pointer 
position escape sequences. 

Thisaction inserts the character or string associated with the 
key that was pressed. 

Thisaction is a synonym for insert)). 

Thisaction inserts an eight-bit (M eta) version of the character 
or string associated with the key that was pressed. T he exact 
action depends on the value of the eightBitinput resource. 
Thisaction inserts the string found in theselection or cut 
buffer indicated by sourcename. Sources are checked in 
theorder given (case is significant) until oneisfound. 
Commonly used selections include primary, secondary, and 
clipboard. Cut buffers are typically named cutbuffero 
through cut_buffer7. 

Thisaction dynamically defines a new translation table whose 
resource name is name with the suffix Keymap (case is signifi¬ 
cant). The name None restorestheoriginal translation table. 
Thisaction displays the specified pop-up menu. Valid names 
(caseissignificant) include mainMenu, vtMenu, fontMenu, and 
tekMenu. 

Thisaction toggles the Secure Keyboard mode described in the 
"Security" subsection, and is invoked from thesecurekbd entry 
in mainMenu. 
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select-start() 


select-extend() 

select-end 

(dest name [, ... ]) 

select-cursor-start() 

select-cursor-end 

(dest name [, ... ]) 

set-vt-font 

(d/1/ 2/ 3/ 4/5/6/e/s 

[, normalfont I, bol dfont ]]) 


start-extendi) 
start-cursor-extend() 
st ring (s t ring) 


scroll-back(count [.units]) 


scroll-forw(count [.units]) 

allow-send-events 
(on/of f/1 oggI e) 
redraw)) 

send-signal(si g n a me) 


quit() 


This action begins text selection at the current pointer 
location. Seethesubsection on "Pointer Usage" for informa¬ 
tion on making selections. 

This action tracks the pointer and extends the selection. It 
should only be bound to M otion events 
This action puts the currently selected text into all of the 
selections or cut buffers specified by dost name. 

Thisaction issimilarto select-start except that it begins the 
selection at the current text cursor position. 

Thisaction issimilarto select-end except that it should 
be used with select-cursor-start. 

This action sets thefont or fonts currently being 
used in theVT 102 window. T hefirst argument isa 
single character that specifies the font to be used: d orD 
indicate the default font (thefont initially used when xterm 
was started), 1 through 6 indicate the fonts specified by the 
fonti through fonts resources, e or e indicate the normal and 
bold fonts that have been set through escape codes (or 
specified asthesecond and third action arguments, respec¬ 
tively), and s ors indicate the font selection (as made by 
programs such asxtontsei(l)) indicated by the second action 
argument. 

Thisaction issimilarto select-start except that the selection 
is extended to the current pointer location. 

Thisaction issimilarto seiect-extend except that the selection 
is extended to the current text cursor position. 

Thisaction inserts the specified text string as if it had been 
typed. Quotation isnecessary if the string contains whitespace 
or nonalphanumeric characters. If the string argument begins 
with the characters ox, it is interpreted as a hex character 
constant. 

Thisaction scrolls the text window backward so that text that 
had previously scrolled off the top ofthescreen is now visible. 
The count argument indicates the number of units (which 
may be page, half page, pixel, or line) by which to scroll. 
Thisaction scroll issimilarto scroll-back except that it scrolls 
the other direction. 

Thisaction set or toggles the aiiowsendEvents resource and is 
also invoked by theaiiowsends entry in mainMenu. 

Thisaction redraws the window and is also invoked by the 
redraw entry in mainMenu. 

Thisaction sends the signal named by s i gname to the xterm 
subprocess (the shell or program specified with the-e 
command-line option) and is also invoked by thesuspend, 
continue, interrupt, hangup, terminate, and kill entries in 
mainMenu. AI lowabl e si gnal names are (case is not significant) 
tstp (if supported by the operating system), suspend (sameas 
tstp), cont (if supported by the operating system), int, hup, 
term, quit, alrm, alarm (same as alrm), and kill. 

This action sends a sighup to the subprogram and exits It is 
also invoked by the quit entry in mainMenu. 
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set-scrollbar(on/of f/1 oggl e) 

set-jumpscroll(on/of f/1 oggl e) 

set-reverse-video(on / of f/1 oggl e) 

set-autowrap(on / of f/1 oggl e) 

set-reversewrap(on/ of f/1 oggl e) 

set-autolinefeed(on / of f /1 oggl e) 

set-appcursor(on/of f/1 oggl e) 

set-appkeypad(on/off/toggl e) 

set-scroll-on-key(on/ of f/1 oggl e) 

set-scroll-on-tty-output(on/of f/1 oggl e) 

set-allowl32(on / of f /1 oggl e) 

set-cursesemul(on/of f/1 oggl e) 

set-visual-bell(on / of f /1 oggl e) 

set-marginbell(on/of f/1 oggl e) 

set-altscreen (on/off/toggl e) 
soft-reset() 

hard-reset() 

clear-saved-lines() 

set-terminal-type(type) 

set-visibility(vt / tek, on/off/toggle) 

set-tek-text(l arge / 2 / 3 / smal I ) 

tek-page() 


Thisaction toggles the scrollbar resource and is also invoked 
by the scrollbar entry in vtMenu. 

Thisaction toggles the jumpscroii resource and is also invoked 
by the jumpscroii entry in vtMenu. 

Thisaction toggles the reversevideo resource and is also 
invoked by the reversevideo entry in vtMenu. 

This action toggles automatic wrappi ng of long lines and is 
also invoked by the autowrap entry in vtMenu. 

Thisaction toggles the reversewrap resource and is also 
invoked by the reversewrap entry in vtMenu. 

Thisaction toggles automatic insertion of line-feeds and is also 
invoked by theautolinefeed entry in vtMenu. 

Thisaction toggles the handling Application Cursor Key mode 
and is also invoked by theappcursor entry in vtMenu. 

This action toggles the handling of Application Key-pad mode 
and is also invoked by theappkeypad entry in vtMenu. 
Thisaction toggles the scroiikey resource and is also 
invoked from the scroiikey entry in vtMenu. 

Thisaction toggles the scroiutyoutput resource and is also 
invoked from thescroiittyoutput entry in vtMenu. 

Thisaction toggles the ci32 resource and is also invoked from 
the allowl32 entry in vtMenu. 

Thisaction toggles the curses resource and is also invoked 
from the cursesemul entry in vtMenu. 

Thisaction toggles the visuaiBeii resource and is also invoked 
by the visualbell entry in vtMenu. 

Thisaction toggles the marginBeii resource and is also invoked 
from the marginbell entry in vtMenu. 

Thisaction toggles between the alternate and current screens. 
Thisaction resets the scrolling region and is also invoked from 
the sbftreset entry in vtMenu. 

Thisaction resets the scrolling region, tabs, window size, and 
cursor keys, and clearsthescreen. It isalso invoked from the 
hardreset entry in vtMenu. 

Thisaction does hard-reset o and also cl ears the history of 
lines saved off the top of thescreen. It isalso invoked from the 
clearsavedlines entry in vtMenu. 

Thisaction directs output to either the vt or tek windows, 
according to the type string. It isalso invoked by thetekmode 
entry in vtMenu and thevtmode entry in tekMenu. 

Thisaction controls whether or not thevt or tek windows 
are visible. It isalso invoked from thetekshowand vthide 
entries in vtMenu and the vtshow and tekhide entries in tekMenu. 
Thisaction sets font used in theT ektronix window to 
the value Of the resources tektextlarge, tektext2, tektext3, 
and tektextsmaii accordi ng to theargument. It isalso 
by the entries of the same names as the resources i n tekMenu. 
Thisaction clears theT ektronix window and isalso invoked 
by the tekpage entry in tekMenu. 
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tek-reset() 

tek-copy() 


visual-bell() 

TheTektronix window also hasthefollowing action: 

gin - press (I / L/m/M/r/R) 

The default bi ndi ngs i n the VT102 window are 

Shift <KeyPress> Prion: scroll-back(1,halfpage) \n\ 

Shift <KeyPress> Next: scroll-forw(1,halfpage) \n\ 

Shift <KeyPress> Select: select-cursor-start() \ 
select-cursor-end(PRIMARY, CUT_BUFFER0) \n\ 

Shift <KeyPress> Insert: insert-selection(PRIMARY, CUT_BUFFER0) \n\ 

'Meta<KeyPress>: insert-seven-bit() \n\ 

Meta<KeyPress>: insert-eight-bit() \n\ 

!Ctrl <Btn1Down>: popup-menu(mainMenu) \n\ 

!Lock Ctrl <Btn1Down>: popup-menu(mainMenu) \n\ 

!Mod2 Ctrl <Btn1Down>: popup-menu(mainMenu) \n\ 

!Mod2 Lock Ctrl <Btn1Down>: popup-menu(mainMenu) \n\ 

'Meta <Btn1Down>: select-start() \n\ 

'Meta <Btn1Motion>: select-extend() \n\ 

!Ctrl <Btn2Down>: popup-menu(vtMenu) \n\ 

!Lock Ctrl <Btn2Down>: popup-m 

The default bindings in theT ektronix window are 

'Meta<KeyPress>: insert-seven-bit() \n\ 

Meta<KeyPress>: insert-eight-bit() \n\ 

!Ctrl <Btn1Down>: popup-menu(mainMenu) \n\ 

!Lock Ctrl <Btn1Down>: popup-menu(mainMenu) \n\ 

!Mod2 Ctrl <Btn1Down>: popup-menu(mainMenu) \n\ 

!Mod2 Lock Ctrl <Btn1Down>: popup-menu(mainMenu) \n\ 

!Ctrl <Btn2Down>: popup-menu(tekMenu) \n\ 

!Lock Ctrl <Btn2Down>: popup-menu(tekMenu) \n\ 

!Mod2 Ctrl <Btn2Down>: popup-menu(tekMenu) \n\ 

!Mod2 Lock Ctrl <Btn2Down>: popup-menu(tekMenu) \n\ 

Shift 'Meta<Btn1Down>: gin-press(L) \n\ 

'Meta<Btn1Down>: gin-press(l) \n\ 

Shift 'Meta<Btn2Down>: gin-press(M) \n\ 

'Meta<Btn2Down>: gin-press(m) \n\ 

Shift 'Meta<Btn3Down>: gin-press(R) \n\ 

'Meta<Btn3Down>: gin-press(r) 

Below is a sample how of thekeymapo action is used to add special keys for entering commonly typed works: 

*VT100.Translations: #override <Key>F13: keymap(dbx) 

VT100.dbxKeymap.translations: \ 

<Key>F14: keymap(None) \n\ 

<Key>F17: string("next") string(0x0d) \n\ 

<Key>F18: string("step") string(0x0d) \n\ 

<Key>F19: string("continue") string(0x0d) \n\ 

<Key>F20: string("print ") insert-selection(PRIMARY, CUT_BUFFER0) 


Thisaction resets theT ektronix window and is also invoked 
by the tekreset entry in tekMenu. 

Thisaction copies the escape codesused to generate the 
currentwindow contents to afilein the current directory 
beginning with the name copy. It is also invoked from the 
tekcopy entry in tekMenu. 

Thisaction flashesthewindow quickly. 


Thisaction sends the indicated graphics input code. 
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ENVIRONMENT 

xterm sets the environment variables term and termcap properly for the size window you have created. It also uses and sets the 
environment variable display to specify which bit map display terminal to use. The environment variable windowid is set to 
theX window id number of the xterm window. 

SEE ALSO 

resize(l), x(l), pty(4), tty(4) 

Xterm Control Sequences 

BUGS 

Large pastes do not work on some systems. This is not a bug in xterm; it is a bug in the pseudo-terminal driver of those 
systems xterm feeds large pastes to the pty only as fast asthepty will accept data, but somepty drivers do not return enough 
information to know if the write has succeeded. 

M any of the options are not resettable after xterm starts. 

Only fixed-width, character-cel I fonts are supported. 

This program still needs to be rewritten. It should be split into very modular sections, with the various emulators being 
completely separate widgets that don't know about each other. Ideally, you'd liketo beableto pick and choose emulator 
widgets and stick them into a single control widget. 

There needs to be a dialog box to allow entry of theT ek copy filename. 

AUTHORS 

Far too many people, including Loretta Guarino Reid (D EC-U EG-WSL), Joel M cCormack (D EC-U EG-WSL), Terry 
Weissman (D EC-U EG-WSL), Edward M oy (Berkeley), Ralph R. Swick (M IT-Athena), M ark Vandevoorde(M IT -Athena), 
Bob M cNamara(DEC-M AD),Jim Gettys(M IT-Athena), BobScheifler (M IT X Consortium), DougM ink(SAO), Steve 
Pitschke(Stellar), Ron Newman (M IT-Athena),Jim Fulton (M IT X Consortium), DaveSerisky (FI P), Jonathan Kamens 
(MIT-Athena) 

X Version 11 Release 6 


Xvfb 

xvfb— Virtual framebuffer X server for X Version 11 

SYNOPSIS 

Xvfb [ option ] ... 

DESCRIPTION 

xvfb is an X server that can run on machines with no display hardware and no physical input devices. It emulates a dumb 
framebuffer using virtual memory. 

The primary use of this server is intended to be server testing. Themfb or cfb code for any depth can be exercised with this 
server without the need for real hardware that supports the desired depths. 

A secondary use istesting clients against unusual depths and screen configurations. 
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OPTIONS 

In addition to the normal server options described in thexserver(l) manual page, xvtb accepts thefollowing command-line 
switches: 


-screen screennum WxHxD 


-pixdepths Ii st■of•dept hs 


-f bdir framebuffer - di rectory 


-shmem 


Thisoption creates screen screennum and sets its width, height, 
and depth to w, h, and d, respectively. By default, only screen 0 
exists and has the dimensions 1280x1024x8. 

Thisoption specifies a list of pixmap depths that the server 
should support in addition to thedepthsimplied by the 
supported screens, iist-of-depths is a space-separated list of 
integers that can have values from 1 to 32. 

Thisoption specifies the directory in which the memory- 
mapped files containing the framebuffer memory should be 
created. (See "Files.") T his option only exists on machines that 
have the mmap and msync system calls. 

Thisoption specifies that the framebuffer should be putin 
shared memory. The shared memory ID for each screen will be 
printed by the server. T he shared memory is in xwd format. 
Thisoption only exists on machines that support the System V 
shared memory interface. 


If neither -shmem nor-fbdir is specified, the framebuffer memory will be allocated with maiioco. 


FILES 

T hefollowing file is created if the -tbdir option isgiven: 

f r a me b u f f e r ■ d i r e c t o r y 
/Xvfb_screen<n> 

EXAMPLES 

Xvfb :1 -screen 0 1600x1200x32 

Xvfb :1 -screen 1 1600x1200x16 


Xvfb -pixdepths 3 27 
-fbdir /usr/tmp 


xwud -in /usr/tmp/Xvfb screen© 

SEE ALSO 

X(l), Xserver(l), xwd(l), xwud(l), XWDFile.h 


M emory-mapped file containing screen n'sframebuffer 
memory, one file per screen. The file is in xwd format. 


Theserver will listen for connections as server number 1, and 
screen 0 will be depth 32 1600x1200. 

Theserver will listen for connections as server number 1, will 
have the default screen configuration (onescreen, 
1280x1024x8), and screen 1 will be depth 16 1600x1200. 
The server will listen for connections as server number 0, 
will have the default screen configuration (onescreen, 
1280x1024x8), will also support pixmap depths of 3 and 27, 
and will use memory-mapped filesin /usr/tmp forthe 
framebuffer. 

D isplays screen 0 of the server started by the preceding 
example. 


AUTHORS 

David P. Wiggins(X Consortium, Inc.) 


X Version 11 Release 6 
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xvidtune 

xvidtune— Video mode tuner for XFree86 

SYNOPSIS 

xvidtune [ -prev j -next j -unlock j -query j -saver s us pendt i me [ offtime ]][-tool ki topti on ... ] 

DESCRIPTION 

xvidtune is a client interface to theXFree86 X server video mode extension (XFree86-VidM odeExtension). 

When given one of the nontoolkit options, xvidtune providesacommand-lineinterfaceto either switch thevideo mode or 
get/set monitor powersaver time-outs. 

Without any options (or with only toolkit options) it presents the user with various buttons and sliders that can be used to 
interactively adjust existing video modes. It will also print the settings in a format suitable for inclusion in an xF86Config file. 


NOTE 


The original mode settings can be restored by pressing the r key, and this can be used to restore a stable screen in situa¬ 
tions where the screen becomes unreadable. 

The available buttons are 

Left 

Right 

Up 

Down 

Adjust thevideo mode so that the display will be moved in the appropriate direction: 

Wider 

Narrower 

Shorter 

Taller 


Adjust thevideo mode so that the display size is altered appropriately: 


Quit 
Apply 
Auto 

Test 
Restore 
Fetch 
Show 

Next 
Prev 

For some S3-based cards (964 and 968) thefollowing are 

InvertVCLK 

EarlySC 


Exit the program. 

Adjust the current video mode to match the selected settings. 
C ausetheU p/D own/Right/Left, W ider/N arrower/Shorter/ 

T aller, Restore, and thespecial S3 buttons to be applied 
immediately. This button can be toggled. 

Temporarily switch to the selected settings. 

Return thesettings to their original values. 

Q uery the server for its current setti ngs. 

Print the currently selected setti ngs to stdout in xF86Config 
Modeiine format. Theprimary selection issimilarly set. 

Switch thexserver to the next video mode. 

Switch thexserver to the previous video mode. 

also available: 

ChangetheVCLK in vert/ n o n i n vert state. 

C hangethe Early SC state. This affects screen wrapping. 
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BiankDeiayi, BiankDeiay2 Set the blank delay values. This affects screen wrapping. 

Acceptable values are in the range 0-7. T he values may be 
incremented or decremented with the +and - buttons, or by 
pressing the + or- keysin thetext field. 

For S3-864/868 based cards, invertvcLK and BiankDeiayi may be useful. For S3 T rio32/T rio64 cards, only invertvcLK is 
available. At the moment there are no default settings avail able for these chips in the video mode extension and thus this 
feature is disabled inxvidtune. It can be enabled by setting any of the optional S3 commands in thescreen section of 
xF86Contig, for example, using 
blank delay 11 " 0 


OPTIONS 

xvidtune accepts the standard X T oolkitcommand-lineoptionsaswell as thefollowing: 

-prev Switch thexserver to the previous video mode. 

-next Switch thexserver to the next video mode. 

-unlock N ormally, xvidtune will disabletheswitching of video modes 

via hot keys while it is running. If for some reason the program 
did not exit cleanly and they are still disabled, the program can 
be rerun with thisoption to reenable the mode switching key 
combinations. 

-saver suspendtime [offtime] Set the suspend and off screen saver inactivity time-outs. The 

values are in seconds. 

-query D isplay the monitor parameters and extended screen saver 

time-outs. 


SEE ALSO 

XF86Config(4/5) 

AUTHORS 

Kaleb S. Keithley (X Consortium), additions and modifications by Jon T ombs, David Dawes, andJoeM oss 

X Version 11 Release 6 
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xvminitoppm— Convert an XV thumbnail picture to PPM 

SYNOPSIS 

xvminitoppm [xvmi ni pi c ] 

DESCRIPTION 

ReadsanXV thumbnail picture (a miniature picture generated by the VisualSchnauzer browser) asinput. Producesa 
portable pixmap as output. 

SEE ALSO 

ppm(5), xv( 1) 

AUTHOR 

Copyright(c) 1993 by Ingo Wilken 


14 D ecember 1993 
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xwd 

xwd— Dump an image of an X window 

SYNOPSIS 

xwd [-debug] [-help] [-nobdrs] [-out file] [-xy] [-frame] [-add value] 
[-root j -id i d j -name name ] [ - icmap] [-screen] [-display display] 


DESCRIPTION 

xwd is an X Window System window dumping utility, xwd allowsX users to store window images in a specially formatted 
dump file This file can then be read by various other X utilities for redisplay, printing, editing, formatting, archiving, image 
processing, and so on. The target window is selected by clicking the pointer in the desired window. The keyboard bell is 
rung once at the beginning of the dump and twice when the dump is completed. 


OPTIONS 

-display di spi ay 

-help 

-nobdrs 


-out file 


-xy 

-add val ue 
-frame 

-root 


-id i ( 


-name name 


-icmap 


-screen 


This argument allows you to specify the server to connect to; 
seex(l). 

Print out theusage: command syntax summary. 

This argument specifies that the window dump should not 
include the pixels that compose the X window border. This is 
useful in situations in which you may wish to include the 
window contentsin adocumentasan illustration. 

This argument allows the user to explicitly specify the output 
file on the command line. The default is to output to standard 
out. 

Thisoption applies to color displays only. 11 selects xy format 
dumpi ng i nstead of the default z format. 

Thisoption specifies a signed value to be added to every pixel. 
Thisoption indicates that thewindow manager frame should 
be included when manually selecting a window. 

Thisoption indicates that the root window should be selected 
for thewindow dump, without requiring the user to select a 
window with the pointer. 

Thisoption indicates that thewindow with the specified 
resource i d should be selected for thewindow dump, without 
requiring the user to select awindow with the pointer. 
Thisoption indicates that thewindow with the specified 
wm_name property should be selected for thewindow dump, 
without requiring the user to select awindow with thepointer. 
N ormally, thecolormap of the chosen window is used to 
obtain RGB values. Thisoption forces the first installed 
colormap of thescreen to beused instead. 

Thisoption indicates that the Getimage request used to obtain 
the image should bedoneon the root window, rather than 
directly on the specified window. In thisway, you can obtain 
pieces of other windows that overlap the specified window, 
and more importantly, you can capture menus or other 
popups that are independent windows but that appear over the 
specified window. 
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ENVIRONMENT 

display To get default host and display number 

FILES 

xwDFiie.h x W indow dump fileformat definition file. 

SEE ALSO 

xwud(l), xpr(l), X(l) 

AUTHORS 

Tony D ella Fera (D igital Equipment Corporation, M IT Project Athena) and William F. Wyatt (Smithsonian Astrophysi cal 
0 bservatory) 

X Verson 11 Releas6 


xwdtopnm 

xwdtopnm— Convert an Xll or X10 window dump file into a portableanymap 

SYNOPSIS 

xwdtopnm [xwdf i I e] 

DESCRIPTION 

Reads an Xll or X10 window dump file as input. Produces a portable anymap as output. The type of the output file 
depends on the input file. If it's black and white, a pbm file iswritten; if it’s grayscale, apgm file else a ppm file. The program 
tells you which type it is writing. 

Using thisprogram, you can convert anything on an X workstation's screen into an anymap. Just display whatever you're 
interested in, do an xwd, run it through xwdtopnm, and then usepnmcut to select the part you want. 

BUGS 

I haven't tested thistool with very many configurations, so there are probably bugs. Please let me know if you find any. 

SEE ALSO 

pnmtoxwd(l), pnm(5), xwd(l) 

AUTHOR 

C opyright (c) 1989,1991 by J ef Poskanzer. 

11 January 1991 


xwininfo 

xwininfo—W indow information utility for X 

SYNOPSIS 


xwininfo [-help] [-id id] [-root] [-name name] [-int] [-children] [-tree] 
[-stats] [-bits] [-events] [-size] [-wm] [-shape] [-frame] [-all] [-english] 
[-metric] [-display di splay] 



xwininfo 



DESCRIPTION 

xwininfo is a uti lity for displaying information about windows. Various information is displayed depending on which options 
are selected. If no options are chosen, -stats is assumed. 

The user has the option of selecting the target window with the mouse (by clicking any mouse button in the desired 
window) or by specifying its window id on the command line with the-id option. Or instead of specifying the window by 
its id number, the -name option may be used to specify which window is desired by name. There is also a special -root 
option to quickly obtain information on the screen's root window. 


OPTIONS 

-help 
-id i d 


-name name 


-roet 


-int 


-children 


-tree 


-stats 


-bits 


-events 


-size 


Print out theusage: command syntax summary. 

Thisoption allows theuser to specify a target window id on 
the command line rather than using the mouse to select the 
target window. This is very useful in debugging X applications 
where the target window is not mapped to the screen or where 
the use of the mouse might be impossible or interfere with the 
application. 

Thisoption allows theuser to specify that thewindow name is 
thetarget window on the command line rather than using the 
mouse to select the target wi ndow. 

Thisoption specifies that X's root window isthe target 
window. This is useful in situations where the root window is 
completely obscured. 

Thisoption specifies that all X window ids should be 
displayed as integer values. The default isto display them as 
hexadecimal values. 

Thisoption causes the root, parent, and children windows' ids 
and names of the selected window to be displayed. 

Thisoption is like -children but displays all children 
recursively. 

Thisoption causes the display of various attributes pertaining 
to the location and appearanceof the selected window. 
Information displayed includes the location of thewindow, its 
width and height, its depth, border width, class, colormap id if 
any, map state, backing-store hint, and location of the corners. 
Thisoption causes the display of various attributes pertaining 
to the selected window's raw bits and how the selected window 
isto be stored. D isplayed information includes the selected 
window's bit gravity, window gravity, backing-store hint, 
backing-planes value, backing pixel, and whether or not the 
window has save-under S6t. 

Thisoption causes the selected window's event masks to be 
displayed. Both theeventmask of events wanted by some 
client and the event mask of events not to propagate are 
displayed. 

Thisoption causes the selected window's sizing hints to be 
displayed. Displayed information includes the following: for 
both the normal size hints and thezoom size hints, theuser 
supplied location, if any; the program supplied location, if any; 
theuser supplied size, if any; the program supplied size, if any; 
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-wm 


-shape 


-frame 


-metric 


-english 


-all 

-display display 


the minimum size if any; the maximum size, if any; the resize 
increments, if any; and the minimum and maximum aspect 
ratios, if any. 

This option causes the selected window's window manager 
hints to bedisplayed. Information displayed may include 
whether or not the application accepts input, what the 
window's icon window # and name is, where the window's 
icon should go, and what the window's initial state should be. 
Thisoption causes the selected window'swindow and border 
shape extents to bedisplayed. 

Thisoption causeswindow manager frames to be considered 
when manually selecting windows. 

Thisoption causes all individual height, width, and x and y 
positionsto bedisplayed in millimeters as well as number of 
pixels, based on what the server thinks the resolution is. 
Geometry specifications that are in +x+y form are not changed. 
Thisoption causes all individual height, width, and x and y 
positionsto bedisplayed in inches (and feet, yards, and miles if 
necessary) aswell as number of pixels, -metric and -english 
may both be enabled at the same time. 

Thisoption is a quick way to ask for all information possible. 
This option allows you to specify the server to connect to; see 
x(l). 


EXAMPLE 

T he following isa sample summary taken with no options specified: 

xwininfo: Window id: 0x60000f "xterm" Absolute upper-left X: 2 
Absolute upper-left Y: 85 Relative upper-left X: 0 Relative upper-left Y: 25 
Width: 579 Height: 316 Depth: 8 Visual Class: Pseudocolor Border width: 0 
Class: InputOutput Colormap: 0x27 (installed) Bit Gravity State: 

NorthWestGravity Window Gravity State: NorthWestGravity Backing Store State: 

NotUseful Save Under State: no Map State: IsViewable Override Redirect State: 
no Corners: +2+85 -699+85 -699-623 +2-623 -geometry 80x24+0+58 

ENVIRONMENT 

display T o get the default host and display number 

SEE ALSO 

x(l), xprop(l) 

BUGS 

Using -stats -bits shows some redundant information. 

The -geometry string displayed must make assumptions about the window's border width and the behavior of the application 
and the window manager. Asa result, the location given is not always correct. 

AUTHOR 

M ark Lillibridge (MIT Project Athena) 


X Version 11 Release 6 
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xwud 

xwud— Imagedisplayer forX 

SYNOPSIS 

xwud [-in file] [-noclick] [-geometry geom] [-display display] 

[-new] [-std <maptype>] [-raw] [-vis <vis-type-or-id>] [-help] [-rv] 
[ - plane number ] [-fg col or ] [ -bg col or ] 


DESCRIPTION 

xwud isan X Window System imageundumping utility, xwud allowsX users to display in awindow an image saved in a 
specially formatted dump file, such as produced byxwd(l). 


OPTIONS 

-bg color 


-display display 


-fg color 


-geometry geom 


-help 
-in file 


-new 


-noclick 


-plane number 


-raw 


If abitmap image (or a single plane of an image) is displayed, 
thisoption can beused to specify the color to display for the 0 
bits in the image. 

This option allows you to specify the server to connect to; see 
x(l). 

If abitmap image (or a single plane of an image) is displayed, 
thisoption can beused to specify the color to display for the 1 
bits in the image. 

Thisoption allows you to specify the size and position of the 
window. Typically, you will only want to specify the position, 
and let the size default to the actual size of the image. 

Print out a short description of the allowable options. 

This option enables the user to explicitly specify the input file 
on thecommand line. If no input fileisgiven, the standard 
input is assumed. 

Thisoption forces creation of a new colormap for displaying 
the image. If the image characteristics happen to match those 
ofthedisplay, thiscan gettheimageon thescreen faster, but 
at the cost of using a new colormap (which on most displays 
will cause other windows to go Technicolor). 

Clicking any button in the window will terminate the 
application, unless this option is specified. Termination can 
always be achieved by typing q, q, orCtrl-tC. 

You can select a single bit plane of the image to display with 
thisoption. Planes are numbered with zero beingthe least 
significant bit. Thisoption can beused to figure out which 
plane to pass to xpr(l) for printing. 

Thisoption forces the image to be displayed with whata/er 
color values happen to currently exist on thescreen. This 
option is mostly useful when undumping an image back onto 
the same screen that the image originally came from, while the 
original windows are still on thescreen, and results in getting 
the image on the screen faster. 

If abitmap image (or a single plane of an image) isdisplayed, 
thisoption forces the foreground and background colors to be 
swapped. This may be needed when displaying a bitmap image 
that has the color sense of pixel values 0 and 1 ra/ersed from 
what they are on your display. 
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-std maptype 


-vis vi s-1 ype-or - i d 


ENVIRONMENT 

DISPLAY 

FILES 

XWDFile.h 

SEE ALSO 

xwd(l), xpr(l), xstdcmap(l), x(l) 

AUTHOR 

BobScheifler(M IT X Consortium) 


Thisoption causes the imageto be displayed usingthe 
specified standard colormap. The property name is obtained 
by converting the type to uppercase, prepending rgb, and 
appending map. Typical types are best, default, and gray. See 
xstd-cmap(l) for oneway of creating standard colormaps. 

This option allows you to specify a particular visual or visual 
class. The default isto pick the"best" one. A particular class 
Can be Specified: StaticGray, Grayscale, StaticColor, 
Pseudocolor, DirectColor, OPTrueColor. Or Match Can be 
specified, meaning use the same class as the source image. 
Alternatively, an exact visual id (specific to the server) can be 
specified, either asa hexadecimal number (prefixed with ox) or 
asadecimal number. Finally, default can be specified, 
meaning to use the same class asthecolormap of the root 
window. Case is not significant in any of these strings. 


To get default display 


X W indow dump file format definition file 
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ybmtopbm 

ybmtopbm— Convert a Bennet Yee"face" file into a portable bitmap 

SYNOPSIS 

ybmtopbm [f acefiI e ] 

DESCRIPTION 

Reads a file acceptable to the face and xbm programs by Bennet Yee(bsy+@cs. cmu.edu). W rites a portable bitmap as output. 

SEE ALSO 

pbmtoybm(l), pbm(5), face(l), face(5), xbm(l) 

AUTHOR 

Copyright (c) 1991 byJamieZawinski and Jef Poskanzer. 


6 March 1990 
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ytalk 

ytaik— A multiuser chat program. 

SYNOPSIS 

ytalk [-x] username... 


DESCRIPTION 

ytaik (V3.0 Patch Level 1) is in essence a multiuser chat program. It works almost exactly liketheU NIX talk program and 
even communicates with the same talk daemon(s), butYTaik allows for multiple connections. 


The username field may be formatted in several different ways: 


name 

name@host 

name#tty 

name#tty@host 

name@host#tty 


Someuser on your machine 

Some user on a different machine 

Someuser on a particular terminal 

Someuser on a particular tty on a different machine 

Same as name#tty@host 


You can specify multiple usernames on thecommand line for example, 
ytalk george fred@hissun.edu marc@grumpy.cc 

The -x option disables the X11 interface (described below). 

For each user on thecommand line, ytaik will attempt to connect to the talk daemon on the specified user's host and 
determine if that user has left an invitation for you to call. If not, ytaik leaves an invitation for him and tells histalk daemon 
to send an announcement to his screen. There is not yet a dedicated ytaik daemon, but there will be. Right now, ytaik is 
ableto communicate with both existing versions of UN IX talk daemons. For any particular host, ytaik will attempt to 
communicate with a talk daemon the caller's host also supports If the two hosts have no daemon in common, then U N IX 
talk will not function at all, but a connection is possible through (and only through) ytaik. 

After a connection has been established between two users, they can chat back and forth to their hearts' content. The 
connection isterminated when oneofthem hitsControl-C or selects Quit from themain menu. 

ytaik is perfectly compatible with U NIX talk and they can even converse with each other without any problems. FI owever, 
many of the features of ytaik can only operate when you are connected to auserwho is also usingytaik. For the rest of this 
document, it will be assumed that all connected users are using ytaik unless otherwise stated. 

If you specified more than oneuser on theytaik command line, then ytaik will process and add each user to the conversa¬ 
tion as they respond to your invitation. Aseach new user enters the conversation, the screen isfurther subdivided into 
smaller and smaller windows, one for each connected user. Right now, the number of connected users is limited by the 
number of lines on your terminal (or window), for each connected user needs at least three lines. 

ytaik does implement primitive support of the X11 Windowing System. If the environment variable display is set, then 
ytaik attempts to connect to thatX server. Further details about the X11 interface (and howto turn it off) are given later in 
thissection. 

Aseach new user is added to the conversation, ytaik will transmit information about that user to all other connected ytaik 
users so that their screens will also subdivide and incorporate the new user. If the new user is using U NIX talk, then 
information about him will N OT be transmitted, ashisscreen would beunableto accept multiple connections. I have given 
brief thought to allowing at least the output of U NIX talk users to be transmitted to all connected ytaik users, but I have not 
written any code to do so. N otethat even though UNIX talk cannot handle multiple connections, it is still possible for ytaik 
to handle multiple U NIX "talk" connections. For example, george (using ytaik) could communicate with fred and joe (both 
using U N IX talk), but fred and joe would be unaware of each other. The best way to understand the limitations that U NIX 
"talk” places on ytaik isto test various connections between the two and see how things work. 
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ESCAPE MENU 

Whenever you are using ytaik, you can hit the Escape key to bring up a menu that at this moment has these options: 
a Add a user 

d Delete a user 

o Options 

s Shell 

u User list 

w 0 utput user to fi le 

q Quit 

By choosing option a, you are given the opportunity to type the name of any user you wish to include into the conversation. 
Again, vtalk will accept an invitation from that user if an invitation exists, or will leave an invitation and ring the given user. 

By choosing option d, you can select the name of a connection to terminate. 

By choosing option o, you can view and/or modify any of the ytaik options. (See the "Options" subsection for a list of ytaik 
options.) 

By choosing option s, you can invoke a shell in your ytaik window. All other users will see what happens in your shell, ytaik 
will automatically resize your window down to the size of the smallest window you are connected to, in order to ensure that 
all users always see the same thing. 

Theu option displays a list of connected and unconnected users, as well as their window sizes and what version of talk 
software th ey are ru n n i n g. 

By choosing option w, you can select any connected user and type the name of a file, and all further output from that user 
will be dumped to the specified file. Thefile, if it exists, will be overwritten. If you choosew and thesameuser again, further 
output to thefile will be terminated. 

Oh, one other thing: when user A attempts to ytaik to user B, but user B is already ytalking with user C, user A's ytaik 
program will realize that user B is already using ytaik, and will communicate with user B's ytaik program directly in order to 
initialize the conversation. User B will see a nice windowed message such as 

Do you wish to talk with user A? 

and he will be prompted for ayes/no answer. This, in my opinion, is much preferable to blitting the announcement message 
and messing up user B's screen. 


RUNTIMEOPTIONS 

When you select Options from the main menu, you are given the opportunity to edit the ytaik options. The current options 
are 


s 

W 

i 

v 

r 

a 


Tum scrolling [off/on] 
Turn word-wrap [off/on] 
Tum auto-import [off/on] 
Tum auto-invite [off/on] 
Tum auto-rering [off/on] 
Tum asides [off/on] 


If scrolling is turned on, then a user's window will scroll when he reaches the bottom, instead of wrapping back around to 
the top. 

If word-wrap isturned on, then any word that would overextend the right margin will be automatically moved to the next line 
on your screen. 



ytalk 



If auto-import is turned on, then ytaik will assume that you wish to talk to any users that connect to other ytaik users that 
are connected to you. That last sentence does make sense; try again, ytaik will add these users to your session automatically, 
without aski ng you for verification. 

If auto-mvite isturned on, then ytaik will automatically accept any connection requested by another user and add the user 
to your session. You will not be asked for verification. 

If auto-rering is turned on, then ytaik will automatically re-ring any user who does not respond to your invitation within 30 
seconds. You will not be asked for verification. 

If asides isturned on (it may not be available), then keyboard input received whilethe input focus isin a specific user's 
window will only be sent to that user. (See the "X11 Interface" subsection.) 

Any of these options can beset to your preference in your .ytaikrc file, as described in the next subsection. 

YTALK STARTUP FILE 

If your home directory contains a file named .ytaikrc, then ytaik will read this file while starting up. All ytaik runtime 
options, as well as some startup options, can beset in thisfile. 

SETTING BOOLEAN OPTIONS 

Boolean optionscan be preset with thefollowing syntax: 
turn opti on [off | on] 

where opt i on is one Of scrolling, word-wrap, auto-import, auto-invite, auto-rering, asides, Of X. Setting these options works 
just like described earlier in this section. T urningx on or off will enable or disable the X11 Interface. For example, one could 
enable word-wrap with the line: 
turn word-wrap on 

SETTING READDRESS MODES 

The purpose of readdressing is to allow ytaik connections across point-to-point network gateways where the local machines 
know themselves by a different address (and typically hostname) than the remote machi nes. T he basic syntax of a readdress 
command is this: 

readdress from-address to- address domain 

The readdress statement simply makes a claim that the machine(s) in domai n communicate with themachine(s) at from- 
address by sending a packet to to-address . Because most users have no use for this whatsoever, I'll describe it only briefly. 

THIS IS NOT ROUTING.For example my machi neat home is connected via PPP to the network at my office. M y 
machine at home thinks its Ethernet address is 192 . 1 88. 253.1 and its hostname is "talisman, com". The network at my office 
has the address 192 . 67 . 141 . 0 . W hen I'm connected via PPP, my home machine is placed into the office network as address 
192.67.141.9 With hostname "talisman.austin.eds.com". 

ytaik needs to know that if it is running on domain 192 . 67 . 141.0 and receives packets from 192 . 1 88. 253.1 that it should 
respond to 192 . 67 . 141 . 9 , not 192 . 1 88. 253 . 1 . Right? Right. Okay, okay, okay. I put this line into my .ytaikrc on both ends: 

readdress talisman talisman.austin.eds.com 192.67.141.0 

On my home end, this translates to 

readdress 192.188.253.1 192.67.141.9 192.67.141.0 

which tells my home machine to advertise itself as 192 . 67 . 141.9 instead of 192 . 1 88. 253.1 when ytalkingto machines on the 
network 192 . 67 . 141 . 0 . 0 n the office end, the readdress command translates to 

readdress 192.67.141.9 192.67.141.9 192.67.141.0 


which the office machines basically ignore. 

Enough. For more information on howto use this, consult the source code or send mealetter.:-) 
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Xll INTERFACE 

If the display environment variable is defined when ytaik starts up, then ytaik will attempt to communicate with thatX 
server. A window will be created for you and each user you are connected to. The Xll Interface can be disabled either by 
specifying -x on the command lineor by putting thislineinto your .ytaikrc file: 
turn X off 

A window iscreated for each individual user in the conversation. Iftheinputfocusisin themain window (theonewith 
ytaik in thetitle bar) then anything typed will be sent to all connected users. If the input focus is in one of the user's 
windows, then anything typed will be sent as an aside to only that user. If the aside option is turned off, then ytaik will beep 
and not accept anything typed when the input focus is not in themain window. 

ytaik consults the Xll Resource D atabase for these user-definable configuration options 
ytaik.display: X server to connect to, defaulting to the display environmentvariable. 
ytaik. reverse: Reverse black/white pixels, 
ytaik.font: Fontto use, defaulting to 9 x 15 . 
ytaik.geometry: W indOW Size, defaulting to 80x24. 

FUTURE WORK 

Work is being done on the following ideas: 

■ Private conversations that do not get interrupted or transmitted to all ytaik connections 

■ A dedicated ytaik daemon 

FILES 

/usr/local/etc/ytalkrc 
$HOME/.ytaikrc 

AUTHOR 

Britt Yenne (yenne@austin.eds.com) 

CONTRIBUTORS 

Special thanks to Carl Edman for numerous code patches, beta testing, and comments I think thisguy spends as much time 
on ytaik as I do. Special thanks to TobiasH ahn and Geoff W. for beta testing and suggestions. Thanks to Sitaram 
Ramaswamy for the original ytaik man page. Thanks to M agnus H ammerin for Solaris 2.* support. Thanks to Jonas 
Yngvesson for aside messages in X. Thanks to Andreas Stolckefor fixing the X resource database cal Is. Thanks to John 
Vanderpool, Shih-Chen Huang, Andrew Myers, Duncan Sinclair, Evan M cLean, and Larry Schwimmer for comments and 
ideas. The readme fileshipped with ytaik gives detailed attributions. 

BUGS 

If you have any ideas, comments or questions, I'd be happy to hear from you atytaik@austin.eds.com. 

24Junel993 


Systemwide defaults file. 

User's local configuration file This file overrides options set in 
the system ytaikrc file 


yuvplittoppm 

yuvpiittoppm— C onvert a y-, au-, and av- file into a portable pixmap. 

SYNOPSIS 

yuvsplittoppm basename width height [ -ccir601] 



zcmp, zdiff 



DESCRIPTION 

Reads three files, containing the YU V components as input. These files are basename.Y, basename.u and basename.v. Produces 
a portable pixmap on stdout. 

Since the YU V files are raw files, the dimensions width and height must be specified on the command line. 

OPTIONS 

■ccir 60 i Assumes that the YU V triplets are scaled into the smaller range 

oftheCCIR 601 (M PEG) standard. Otherwise, theJFIF 
(JPEG) standard is assumed. 

SEE ALSO 

ppmtoyuvsplit(l), yuvtoppm(l), ppm(5) 

AUTHOR 

M arcel W ijkstra (<wi]kstra@fwi.uva.nl>), based on ppmtoyuvsplit 

26 August 1993 


yuvtoppm 

yuvtoppm— C onvert Abekas YU V bytes into a portable pixmap 

SYNOPSIS 

yuvtoppm wi dt h height [imagedata] 

DESCRIPTION 

Reads raw Abekas YU V bytes asinput. Produces a portable pixmap as output. Theinput file is just YU V bytes. You have to 
specify the width and height on the command line si nee the program obviously can't get them from the file Themaxvai is 
assumed to be 255. 

SEE ALSO 

ppmtoyuv(l), ppm(5) 

AUTHOR 

M arc Boucher (<manc§Postimage.coM>)), based on Example Conversion Program, A60/A64 Digital Video Interface Manual, 
page69. Copyright (c) 1991 by D H D Postlmage, Inc. Copyright (c) 1987 byAbekas Video Systems, Inc. 

25 March 1991 


zcmp, zdiff 

zcmp, zdiff — C ompare compressed fi les 

SYNOPSIS 


zcmp [ cmp_options ] filel [ file2 ] 
zdiff [diff_options ] filel [ file2 ] 
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DESCRIPTION 

zcmp and zdift areused to invokethecmp orthediff program on compressed files. All options specified are passed directly to 
cmp or diff. If only one file is specified, then the files compared aretiiei and an uncompressed mei .gz. If two files are 
specified, then they are uncompressed if necessary and fed to cmp or diff. The exit status from cmp or diff is preserved. 

SEE ALSO 

cmp(l), diff(l), zmore(l), zgrep(l), znew(l), zforce(l), gzip(l), gzexe(l) 

BUGS 

M essages from the cmp or diff programs refer to temporary filenames instead of those specified. 

zeisstopnm 

zeisstopnm — C onvert a Zeiss confocal file into a portable anymap 

SYNOPSIS 

zeisstopnm [-p g m j -ppm] [zei ssf i I e] 

DESCRIPTION 

Reads a Zeiss confocal fi le as i nput. Produces a portable anymap as output. T he type of the output file depends on the input 
file-if it's grayscale, a pgm file will be produced; otherwise, it will beappm file The program tells you which type it is 
writing. 

OPTIONS 

-pgm Force the output to be a pgm file 

-ppm Force the output to beappm file 

SEE ALSO 

pnm(5) 

AUTHOR 

C opyright (c) 1993 by 0 liver T repte. 

15Junel993 


zforce 

zforce — Force a .gz extension on all gzip files 

SYNOPSIS 

zforce [ name ... ] 

DESCRIPTION 

zforce forces a .gz extension on all gzip files so that gzip will not compress them twice. This can be useful for files with 
names truncated after a file transfer. On systemswith a 14-character limitation on filenames, theoriginal nameistruncated 
to make room for the .gz suffix. For example, 12345678901234 is renamed to 12345678901 .gz. A filename such asfoo.tgz is left 
intact. 
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SEE ALSO 

gzip(l), znew(l), zmore(l), zgrep(l), zdiff(l), gzexe(l) 


zgrep 

zgrep — Search possibly compressed files for a regular expression 

SYNOPSIS 

zgrep [ grep_options ] [-e] pattern filename... 

DESCRIPTION 

zgrep is used to invoke the grep on compressed orgziped files. All options specified are passed directly to grep. If no file is 
specified, then the standard input is decompressed if necessary and fed to grep. Otherwise, the given files are uncompressed if 
necessary and fed to grep. 

If zgrep is invoked aszegrep or zfgrep, then egrep ortgrep is used instead of grep. If the grep environment variable is set, 
zgrep uses it as the grep program to beinvoked. For example 

for sh: GREP=fgrep zgrep string files for csh: (setenv GREP fgrep; zgrep string files) 

AUTHOR 

C harles L evert (charles@comm. polymtl.ca) 

SEE ALSO 

grep(l), egrep(l), fgrep(l), zdiff(l), zmore(l), znew(l), zforce(l), gzip(l), gzexe(l) 


zmore 

zmore— File perusal filter for crt viewing of compressed text 

SYNOPSIS 

zmore [ name ... ] 

DESCRIPTION 

zmore is a filter that allows examination of compressed or plain text files one screenful atatimeon a soft-copy terminal, zmore 
works on files compressed with compress, pack, orgzip, and also on uncompressed files. If a file does not exist, zmore looks for 
a file of the same name with the addition of a .gz, .z, or .z suffix. 

zmore normally pauses after each screenful, printing -More- at the bottom of thescreen. If the user then types a carriage 
return, one more line isdisplayed. If the user hits a space, another screenful isdisplayed. Other possibilities are enumerated 
later. 

zmore looks in the file /etc/termcap to determine terminal characteristics, and to determine the default window size. On a 
terminal capable of displaying 24 lines, the default window size is 22 lines. To use a pager other than the default more, set 
environment variable pager to the name of the desired program, such as less. 

Other sequences that may be typed when zmore pauses, and their effects, are as follows (i isan optional integer argument, 
defaulting to i): 

i <space> D isplay i more lines, (or another screenful if no argument is 

given). 

'd D isplay 11 more lines (a "scroll"). If i is given, then the scroll 

si ze i s set to i. 

d Sameas ‘d (controi-D) 
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i S 

i f 
q OrQ 
e Of q 

s 


i /expr 


i n 


!command 


:q Of :Q 


Same as typing a space except that i, if present, becomes the 
new window size. N otethat thewindow size reverts back to 
the default at the end of the current file. 

Skip i lines and print a screenful of lines. 

Skip i screenfuls and print a screenful of lines. 

Quit reading the current file; go on to the next (if any). 

When the prompt -More-(Next file: file) isprinted, this 
command causes zmore to exit. 

When the prompt -More-(Next file: fi i e ) isprinted, this 
command causes zmore to skip the next file and continue. 

D i splay the current line number. 

Search for the i th occurrence of the regular expression expr. If 
the pattern is not found, zmore goes on to the next file (if any). 
Otherwise, ascreenful isdisplayed, starting two lines before 
theplacewheretheexpression was found. The user's erase and 
kill characters may be used to edit the regular expression. 
Erasing back past the first column cancels the search 
command. 

Search for the i th occurrenceof the last regular expression 
entered. 

I nvoke a shell with command. The character : in command is 
replaced with the previous shell command. The sequence)! is 
replaced by!. 

Quit reading the current file; go on to the next (if any) (same 
asq or q). 

(dot) Repeat the previous command. 


The commands take effect immediately; that is it is not necessary to type a carriage return. Up to the time when the 
command character itself is given, the user may hit the line kill character to cancel the numerical argument being formed. In 
addition, the user may hit the erase character to redisplay the -More- message. 

At any time when output is being sent to the terminal, the user can hit the quit key (normally Control-n). zmore will stop 
sending output, and will display the usual -More- prompt. The user may then enter one of the preceding commands in the 
normal manner. U nfortunately, some output is lost when this is done because any characters waiting in the terminal's output 
queue are flushed when the quit signal occurs 

Theterminal is set to noecho mode by thisprogram so that the output can be continuous. What you type will thusnotshow 
on your terminal, except for the / and ! commands 

If the standard output is not a teletype, then zmore acts just like zcat, except that a header isprinted before each file. 


FILES 

/etc/termcap Terminal database 


SEE ALSO 

more(l), gzip(l), zdiff(l), zgrep(l), znew(l), zforce(l), gzexe(l) 


znew 

znew — RecompressZ files to GZ files 

SYNOPSIS 


znew [ -ftv9PK] [ name.Z ... ] 



zn&v 
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DESCRIPTION 

znew recompresses files from Z (compress) format to GZ (gzip) format. If you want to recompress a file already in gzip 
format, rename the file to forcea .z extension, then apply znew. 

OPTIONS 

-t 

-t 

-V 

-9 
-P 
-K 

SEE ALSO 

gzip(l), zmore(l), zdiff(l), zgrep(l), zforce(l), gzexe(l), compress(l) 

BUGS 

znew does not maintain the timestamp with the -p option if cpmod(l) is not available and touch(l) does not support the -r 
option. 


Force recompression from Z to GZ format even if a GZ file 
already exists. 

T est the new files before deleting originals. 

Verbose. D isplay the name and percentage reduction for each 
filecompressed. 

Usetheslowest compression method (optimal compression). 
Use pipes for the conversion to reduce disk space usage. 

Keep aZ filewhen it issmaller than theGZ file. 
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intro 

intro— I introduction to system calls 

DESCRIPTION 

T h i s ch apter descri bes the Linux system cal Is. 

CALLING DIRECTLY 

In most cases, it is unnecessary to invoke a system call directly, but there are times when the standard C library does not 
implement a nice function call for you. 

SYNOPSIS 

#include <linux/unistd.h> 

A _syscaii macro 
Desired system call 

SETUP 

T he important thing to know about a system call is its prototype. You need to know how many arguments their types, and 
thefunction return type. Six macros make the actual call into the system easier. They havetheform 
syscallX(t ype,name,typel,argl,type2,arg2,...) 

where 

x 0-5, which arethe number of arguments taken by the system call 

type The return type of the system call 

name Thenameof the system call 

typeN The Nth argument's type 

a r g n T he name of the N th argument 

These macros create a function called name with the arguments you specify. 0 nee you i nclude syscall () in your source file, 
you call the system call byname. 

EXAMPLE 

t 

struct sysinfo s_info; 
int error; 

error = sysinfo(&s_info); 
printf("code error = %d\n", error); 

printf("Uptime = %ds\nLoad: 1 min %d / 5 min %d / 15 min %d\n" 

"RAM: total %d / free %d / shared %d\n" 

"Memory in buffers = %d\nSwap: total %d / free %d\n" 

"Number of processes = %d\n", 
s_info.uptime, s_info.loads[0], 
s_info.loads[1], s_info.loads[2], 
s_info.totalram, s_info.freeram, 
s_info.sharedram, s_info.bufferram, 
s_info.totalswap, s_info.freeswap, 
s_info.procs); 
return(0); 

} 
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SAMPLE OUTPUT 

code error = 0 
uptime = 502034s 

Load: 1 min 13376 / 5 min 5504 / 15 min 1152 

RAM: total 15343616 / free 827392 / shared 8237056 

Memory in buffers = 5066752 

Swap: total 27881472 / free 24698880 

Number of processes = 40 

NOTES 

The_syscaii() macros do not produce a prototype. You might have to createone, especially for C-H-users. 

System calls are not required to return only positive or negative error codes. You need to read the source to be sure how it 
will return errors. Usually, it is the negative of a standard error code, for example, -eperm. The_syscaii() macroswill return 
the result r of the system call when r is nonnegative, but will return -i and set the variable errno to -r when r isnegative. 

Some system calls, such asmmap, require more than five arguments. These are handled by pushing the arguments on the stack 
and passing a pointer to the block of arguments. 

When defining a system call, the argument types must be passed by value or by pointer (for aggregates such as structs). 

FILES 


/usr/include/linux/unistd.h 

AUTHORS 

Look at the header of the manual page for the author(s) and copyright conditions. N ote that these can be different from page 
to page. 

Linux 1.2.13, 22 May 1996 


exit 

exit— Terminate the current process 

SYNOPSIS 

#include <unistd.h> 
void exit(int status); 

DESCRIPTION 

exit terminates the calling process immediately. Any open file descriptors belonging to the process are closed; any children of 
the process are inherited by process i, init, and the process's parent is sent a sigchld signal. 

status is returned to the parent process as the process's exit status and can be collected using one of the wait family of calls. 

RETURN VALUE 

exit never returns. 

C0NF0RMST0 

SVID, AT&T, PO SIX, X/O PEN , BSD 4.3 

NOTES 

exit does not call any functions registered with the AN SI C atexit function and does not flush standard I/O buffers. To do 
these things, useexit(3). 
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SEE ALSO 

fork(2), execve(2), waitpid(2), wait4(2), kill(2), wait(3), exit(3) 


Linux, 21 July 1993 


accept 

accept— Accept a connection on a socket 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/socket.h> 

int accept(int s, struct sockaddr *addr ,int*addrI en); 

DESCRIPTION 

Thearguments is a socket that has been created with sockets), bound to an address with bind ( 2 ), and is listeni ng for 
connections after a listen ( 2 ). The accept function extracts the first connection request on the queue of pending connec¬ 
tions, creates a new socket with the same properties of s, and allocates a new file descriptor for the socket. If no pending 
connections are present on the queue and the socket is not marked as nonblocking, accept blocks the caller until a connec¬ 
tion ispresent. I f the socket ismarked nonblocking and no pending connections are present on the queue, accept returnsan 
error as descri bed below. The accepted socket may not be used to accept more connections. The original sockets remains 
open. 

The argument a ddr is a result parameter that is filled in with the address of the connecting entity, as known to the communi¬ 
cations layer. The exact format of theaddr parameter is determined by the domain in which the communication is occurring. 
T he a dd r i en is a value-result parameter; it should initially contain the amount of space pointed to by a ddr; on return it will 
contain the actual length (in bytes) of the address returned. This call is used with connection-based socket types, currently 

with SOCK_STREAM. 

It ispossibleto select( 2 ) a socket for the purposes of doing an accept by selecting it for read. 

For certain protocols that require an explicit confirmation, such as iso and datakit, accept can bethought of as merely 
dequeuing the next connection request and not implying confirmation. Confirmation can be implied by a normal read or 
write on the new file descriptor, and rejection can be implied by closing the new socket. 

One can obtain user connection request data without confirming the connection by issuing a recvmsg( 2 > call with amsg 
iovien of 0 and a nonzero msg controller!, or by issuing a getsockopt( 2 ) request. Similarly, one can provide user connection 
rejection information by issuing a sendmsg( 2 ) call providing only the control information, or by calling setsockopt( 2 ). 

RETURN VALUES 

The call returns-i on error. If it succeeds, it returns a nonnegative integer that is a descriptor for the accepted socket. 

ERRORS 

EBADF 
ENOTSOCK 
EOPNOTSUPP 
EFAULT 
EWOULDBLOCK 

HISTORY 

The accept function appeared in BSD 4.2. 


The descriptor is invalid. 

T he descriptor references a file not a socket. 

T he referenced socket is not of type sock_stream. 

Theaddr parameter isnot in a writable part of the user address space. 

The socket ismarked nonblocking and no connections are present to be accepted. 
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SEE ALSO 

bind(2), connect(2), listen(2), select(2), socket(2) 

BSD Man Page, 24July 1993 


access 

access— C hecksuser's permissionsfor a file 

SYNOPSIS 

#include <unistd.h> 

int access(const char *pat h n a me,intmode); 

DESCRIPTION 

access checks whether the process would be allowed to read, write, or test for existence of the file (or other file system object) 
whose name ispathname. If pathname is a symbolic link, permissions of the file referred by this symbolic link are tested. 

mode is a mask consisting of one or more of r ok, w_ok, x_ok, and f_ok. 

r ok, w_ok, and x_ok request checking whether thefile exists and has read, write, and execute permissions, respectively, fjk 
just requests checki ng for the existence of thefile 

The tests depend on the permissions of the directories occurring in the path to thefile, as given inpathname, and on the 
permissions of directories and files referred by symbolic links encountered on the way. 

Thecheck isdonewith the process's real UID and GID, rather than with theeffectivelDsasisdonewhen actually 
attempting an operation. This is to allow set-U ID programs to easily determine the invoking user's authority. 

Only access bits are checked, not the file type or contents. Therefore, if a directory is found to be "writable,'' it probably 
means that files can be created in the directory, and not that the directory can be written as a file Similarly, a DOS file may 
be found to be "executable,'' buttheexecve( 2 ) call will still fail. 

RETURN VALUE 

On success (all requested permissions granted), 0 is returned. On error (at least 1 bit in mode asked for a permission that is 
denied, or some other error occurred), -1 is returned and errno is set appropriately. 

ERRORS 

EACCES 

EFAULT 
EINVAL 

ENAMETOOLONG 
ENOENT 

ENOTDIR 
ENOMEM 
ELOOP 

RESTRICTIONS 

access returns an error if any of the access types in the requested call fails, even if other types might be successful, access may 
not work correctly on N FS file systems with UID mapping enabled because UID mapping is done on the server and hidden 
from the client, which checks permissions. 


The requ ested access would be denied, either to the fi le itself oroneofthedi recto ri es i n 

p a t h n a me. 

p a t h n a me poi nts outsi de your accessi bl e address space, 
mode was incorrectly specified, 
pathname istOO long. 

A directory component in pathname would have been accessible but does not exist or was a 
dangling symbolic link. 

A component used as a directory in pathname isnot, in fact, a directory. 
Insufficientkernelmemorywasavailable. 

pathname contains a reference to a circular symbolic link, that is, a symbolic link containing 
a reference to itself. 
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CONFORMSTO 

SVID, AT&T, POSIX, X/OPEN , BSD 4.3 

SEE ALSO 

stat(2), open(2), chmod(2), chown(2), setuid(2), setgid(2) 

Linux 1.2.13,17 M arch 1996 


acct 

acct— Switches process accounting on or off 

SYNOPSIS 

#include <unistd.h> 

int acct(const char filename); 

DESCRIPTION 

Warning: Since this function is not implemented as of Linux 0.99.11, itwill always return -i and set ermo to enosys. If 
acctkit is installed, the function performs as advertised. 

When called with the name of an existing file as argument, accounting is turned on and records for each terminating process 
are appended to f i i ename as it terminates. An argument of null causes accounting to be turned off. 

RETURN VALUE 

O n success, 0 is returned. 0 n error, -1 is returned and errno is set appropriately. 

NOTES 

N 0 accounting is produced for programs running when a crash occurs. In particular, nonterminating processes are never 
accounted for. 

SEE ALSO 

acct(5) 

Linux 0.99.11,10 August 1993 


adjtimex 

adjtimex— Tunes kernel clock 

SYNOPSIS 

#include <sys/timex.h> 

int adjtimex(struct timex *buf); 

DESCRIPTION 

Linux uses David M ill's clock adjustment algorithm, adjtimex reads and optionally sets adjustment parameters for this 
algorithm. 

adjtimex takes a pointer to a t i mex structure, updates kernel parameters from field values, and returns the samestructure with 
current kernel values. This structure is declared as follows: 



adjtimex 



struct timex 

{ 

int mode; 



/* 

mode selector */ 

long offset; 

/* 

time offset (usee) */ 

long frequency; 

/* 

frequency offset (scaled ppm) */ 

long maxerror; 

/* 

maximum error (usee) */ 

long esterror; 

/* 

estimated error (usee) */ 

int status; 

/* 

clock command/status */ 

long time_constant; 

/* 

pll time constant */ 

long precision; 

/* 

clock precision (usee) (read only) 

long tolerance; 

/* 

clock frequency tolerance (ppm) 



(read only) */ 

struct timeval time; 

/* 

(read only) */ 

long tick; 

}; 

/* 

usees between clock ticks */ 


The mode field determines which parameters, if any, to set. It may contain a bitwise-or combination of zero or more of the 
following bits: 


#define ADJ OFFSET 


0 x0001 /* time offset */ 


#define ADJ_FREQUENCY 
#define ADJ_MAXERROR 
#define ADJ_ESTERROR 
#define ADJ_STATUS 
#define ADJ_TIMECONST 
#define ADJ TICK 


0 x0002 /* frequency offset */ 
0x0004 /* maximum time error */ 
0x0008 /* estimated time error */ 
0 x0010 /* clock status */ 

0 x0020 /* pll time constant */ 
0x4000 /* tick value */ 


#define ADJ_OFFSET_SINGLESHOT 0x8001 /* old-fashioned adjtime */ 


Ordinary users are restricted to a 0 value for mode. Only the superuser may set any parameters. 


RETURN VALUE 

On success, adjtimex returns the value of buf. st at us: 

#define TIME OK 0 /* clock synchronized */ 

#define TIME INS 1 /* insert leap second */ 

#define TIME DEL 2 /* delete leap second */ 

#define TIME OOP 3 /* leap second in progress */ 

#define TIME BAD 4 /* clock not synchronized */ 

On failure, adjtimex returns-i and setserrno. 


ERRORS 

EFAULT 

EPERM 

EINVAL 


SEE ALSO 

settimeofday(2) 


buf does not point to writable memory. 

buf. mode is nonzero and the user is not superuser. 

An attempt is made to set buf. offset to a value outside the range-131071 to +131071, or 
to set buf. status to a value other than those listed above, or to set buf. ti ck to a value 
outside the range 900000/HZ to 1100000/HZ,where HZ is the system timer interrupt 
frequency. 


Linux 1.2.4,15 April 1995 
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alarm 

alarm— Sets an alarm clock for delivery of a signal 

SYNOPSIS 

#include <unistd.h> 

unsigned int alarm(unsigned int seconds); 

DESCRIPTION 

alarm arranges for a sigalrm signal to be delivered to the process in seconds seconds. 

If seconds is 0, no new alarm is scheduled. 

In any event, any previously set alarm is canceled. 

RETURN VALUE 

alarm returns the number of seconds remaining until any previously scheduled alarm was due to be delivered, ore if there 
was no previously scheduled alarm. 

NOTES 

alarm and setitimer share the same timer; calls to one will interfere with use of the other. 

Scheduling delays can, as ever, cause the execution of the process to be delayed by an arbitrary amount of time 

C0NF0RMST0 

SVID, AT&T, POSIX, X/OPEN , BSD 4.3 

SEE ALSO 

setitimer(2), signal(2), sigaction(2), gettimeofday(2), select(2), pause(2), sleep(3) 

Linux, 21 July 1993 


bdflush 

bdfiush — Starts, flushes, or tunes the buffer-dirty-flush daemon 

SYNOPSIS 

int bdflush(int func, long *address); 
int bdflush(int func, long data); 

DESCRIPTION 

bdfiush starts, flushes, or tunes the buffer-dirty-flush daemon. Only the superuser may call bdfiush. 

If tunc is negative or o and no daemon has been started, bdfiush enters the daemon code and never returns. 

If tunc is i, some dirty buffers are written to disk. 

If tunc is 2 or more and is even (low bit is 0 ), address isthe address of a long word, and the tuning parameter numbered 
(func -2)/2 is returned to the caller in that address. 

If func is 3 or more and is odd (low bit is 1 ), data is a long word and the kernel sets tuning parameter numbered (func - 3 )/2 
to that value. 

The set of parameters, their values, and their legal ranges are defined in the kernel source filet s/buf f er. c. 



bind 



RETURN VALUE 

If f unc is negative or 0 and the daemon successfully starts, bdtiush never returns. Otherwise, the return value is 0 on success 
and -1 on failure, with errno set to indicate the error. 

ERRORS 

eperm Caller is not superuser. 

efault address points outside your accessible address space. 

ebusy An attempt was madeto enter the daemon code after another process has already been 

entered. 

einval An attempt was madeto read or write an invalid parameter number, or to write an invalid 

value to a parameter. 

SEE ALSO 

fsync(2), sync(2), update(8), sync(8) 

Linux 1.2.4,15 April 1995 


bind 

bind— Binds a name to a socket 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/socket.h> 

int bind(int sockfd, struct sockaddr *my _ addr ,inta ddrI en ); 

DESCRIPTION 

bind gives the socket, sockfd, the local address my_ a dd r. my_addr isaddr I en bytes long. T raditionally, this iscalled assigning a 
name to a socket. (W hen a socket is created with socket(2), it exists in a namespace—an address family— but has no name 
assigned.) 

NOTES 

Binding a name in theU NIX domain creates a socket in the file system that must be deleted by the caller— using uniink(2) 
— when it is no longer needed. 

The rules used in namebinding vary between communication domains. Consult the manual entries in section 4 for detailed 
information. 

RETURN VALUE 

On success, 0 is returned. 0 n error, -1 is returned, and errno is set appropriately. 

ERRORS 

ebadf sockfd isnotavalid descriptor. 

einval The socket is already bound to an address. This may change in the future. Seeimux/unix/ 

sock.c for details. 

eacces The address is protected and the user is not the superuser. 

The following errors are specific to UNIX domain (afjjnix) sockets: 

einval addr i en was wrong, or the socket was not in the af unix family. 

erofs The socket inode would resideon a read-only filesystem. 

efault my_a dd r points outside your accessible address space. 
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ENAMETOOLONG 

ENOENT 

ENOMEM 

ENOTDIR 

EACCES 

ELOOP 


my_addr istOO long. 

T he file does not exist. 

Insufficientkernelmemorywasavailable. 

A component of the path prefix is not a directory. 

Search permission isdenied on acomponent of the path prefix, 
my. ad dr contains a circular reference (that is, via a symbolic link). 


HISTORY 

The bind function call appeared in BSD 4.2. 


SEE ALSO 

accept(2), connect(2), listen(2), socket(2), getsockname(2) 


Linux0.99.11, 23July 1993 


brk, sbrk 

brk, sbrk— C hange data segment size 

SYNOPSIS 

#include <unistd.h> 

int brk(void *end_data_segment ); 

void *sbrk(ptrdiff tincrement); 

DESCRIPTION 

brk sets the end of the data segment to the value specified by end. data, segment. 

end.data.segment must be greater than the end of the text segment and it must be 16KB before the end of the stack, 
sbrk increments the program's data space by i ncrement bytes, sbrk isn't a system call; it is just a C library wrapper. 

RETURN VALUE 

On success, brk returns a, and sbrk returns a pointer to the start of the new area. On error, -i is returned and errno is set to 

ENOMEM. 

C0NF0RMST0 

BSD 4.3 

brk and sbrk are not defined in the C standard and are deliberately excluded from thePOSIX.1 standard (see paragraphs 
B.l.1.1.3 and B.8.3.3). 

SEE ALSO 

execve(2), getrlimit(2), malloc(3), end(3) 

Linux0.99.11, 21 July 1993 


cacheflush 

cachetiush — Flushes contents of the instruction and/or data cache 


SYNOPSIS 



chdir, fchdir 

#include <asm/cachectl.h> 
int cacheflush(char *addr ,intnbytes,intcache); 

DESCRIPTION 

cachefiush flushes contents of indicated cache! s) for user addresses in the range addr to (addr+nbytes-i). The cache may be 
oneof the followi ng: 

icache Flush the instruction cache. 

dcache W rite back to memory and invalidate the affected valid cache lines. 

bcache Same as (icachei dcache). 

RETURN VALUE 

cachefiush returns© on successor -i on error. If errors are detected, errno will indicate the error. 

ERRORS 

einval T he cache parameter is not one of icache, dcache, or bcache. 

efault Someorall of the address range addr to (addr+nbytes-i) is not accessible. 

BUGS 

Thecurrent implementation ignores the addr and nbytes parameters. Therefore, thewholecache is always flushed. 

NOTE 

Thissystem call isonly availableon M IPS-based systems. 

SEE ALSO 

cachectl(2) 

Linux, 21 June95 

chdir,fchdir 

chdir, fchdir— C hanges the working directory 

SYNOPSIS 

#include <unistd.h> 

int chdir(const char *path); 

int fchdir(int f d); 

DESCRIPTION 

chdir changes the current directory to that specified in path. 

fchdir isidentical to chdir, only the directory is given as an open file descriptor. 

RETURN VALUE 

On success, 0 is returned. 0 n error, -1 is returned, and errno is set appropriately. 

ERRORS 

Depending on the file system, other errors can be returned. The more general errors are listed here: 
eperm The process does not have execute permission on the directory. 

path points outside your accessible address space, 
pat h istoo long. 



EFAULT 

ENAMETOOLONG 
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EBADF 

fd isnotavalid file descriptor. 

ENOENT 

Thefiledoes not exist. 

ENOMEM 

Insufficientkernelmemorywasavailable. 

ENOTDIR 

A component of the path prefix is not a directory. 

EACCES 

Search permission isdenied on acomponent of the path prefix. 

ELOOP 

path contains a circular reference (that is, via a symbolic link) 

SEE ALSO 


getcwd(3), chroot(2) 

Linux 1.2.4,15 April 1995 

chmod,fchmod 


chmod, fchmod — C hanges permissions of a file 

SYNOPSIS 


#include <sys/types.h> 
#include <sys/stat.h> 


int chmod(const char *p a t h ,modetmo de ); 
int fchmod(int f i 1 des , modetmo de ); 

DESCRIPTION 


Themodeof the file gi ven by 

path or referenced bytiiedes ischanged. 

M odes are specified by oring thefollowing: 

S_ISUID 

04000 Set user ID on execution 

S_ISGID 

02000 Set group ID on execution 

S_ISVTX 

01000 Sticky bit 

S_IRUSR (S_IREAD) 

00400 Read by owner 

s_iwusr (s_iwrite) 

00200 Write by owner 

S_IXUSR (S_IEXEC) 

00100 Execut^search by owner 

S_IRGRP 

00040 Read by group 

S_IWGRP 

00020 W rite by group 

S_IXGRP 

00010 Execut^search by group 

S_IROTH 

00004 Read by others 

S_IWOTH 

00002 W rite by others 

S_IXOTH 

00001 ExecuWsearch by others 

The effective U ID of the process must beO or must match the owner of the file. 

The effective U ID orGID must be appropriate for setting execution bits 


Depending on the file system, set user ID and set group ID execution bits may be turned 
off if a file is written. On some file systems, only the superuser can set the sticky bit, which 
may have a special meaning (that is, for directories, a file can only be deleted by the owner 
or the superuser). 

RETURN VALUE 


0 n success, 0 is returned. 0 n error, -1 is returned and errno isset appropriately. 



chown, fchown 


749 


ERRORS 

Depending on the file system, other errors can be returned. The more general errors for chmod are listed here 


EPERM 

EROFS 

EFAULT 

ENAMETOOLONG 

ENOENT 

ENOMEM 

ENOTDIR 

EACCES 

ELOOP 


The effective U ID does not match the owner of the file and is not 0. 
T he named fi le resides on a read-only file system, 
path points outside your accessible address space, 
path istoo long. 

Thefiledoes not exist. 

Insufficientkernelmemorywasavailable. 

A component of the path prefix is not a directory. 

Search permission isdenied on acomponent of the path prefix, 
path contains a circular reference (that is, via a symbolic link) 


The general errors for f chmod are listed here: 

ebadf The descriptor is not value. 

enoent See above. 

eperm See above. 

erofs See above. 


SEE ALSO 

open(2), chown(2), stat(2) 


Linux 0.99.11, 21 July 1993 


chown, fchown 

chown, fchown— Changes ownership of a file 

SYNOPSIS 

#include <sys/types.h> 

#include <unistd.h> 

int chown(const char *p a t h, uid t owner, gid_t group); 
int fchown(int f d, uid t owner , gid_t group); 

DESCRIPTION 

The owner of the file specified bypath or by f d is changed. Only the superuser may change the owner of a file. The owner of 
a file may change the group of the file to any group of which that owner is a member. The superuser may change the group 
arbitrarily. 

If the owner or gr oup is specified as-i, that ID isnot changed. 

RETURN VALUE 

On success, 0 is returned. 0 n error, -1 is returned and errno isset appropriately. 

ERRORS 

Depending on the file system, other errors can be returned. The more general errors for chown are listed here 

eperm T he effective U ID doesnot match theowner of thefile, and isnot 0; ortheowner or gr oup 

were specified incorrectly. 

erofs The named file resides on a read-only file system. 

efault path pointsoutsideyouraccessibleaddressspace. 
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ENAMETOOLONG 

ENOENT 

ENOMEM 

ENOTDIR 

EACCES 

ELOOP 


path istoo long. 

T he file does not exist. 
Insufficientkernelmemorywasavailable. 

A component of the path prefix is not a directory. 

Search permission isdenied on acomponent of the path prefix, 
path contains a circular reference (that is, via a symbolic link). 


The general errors for tchown are listed here: 

ebadf The descriptor is not value. 

enoent See above. 

eperm See above. 

erofs See above. 


NOTES 

chown does not follow symbolic links The prototype for fchown is only available if use bsd is defined. 

SEE ALSO 

chmod(2), flock(2) 

Linux 0.99.11 21 July 1993 


chroot 

chroot— C hanges root di rectory 

SYNOPSIS 

#include <unistd.h> 

int chroot(const char *path); 


DESCRIPTION 

chroot changes the root directory to that specified in path. This directory will be used for pathnames beginning with /.The 
root directory is inherited by all children of the current process. 

0 nly the superuser may change the root directory. 

Note that this cal I does not change the current working directory, so that. can be outside the tree rooted at/. 


RETURN VALUE 

On success, 0 is returned. On error, -1 isreturned and errno is set appropriately. 


ERRORS 


Depending on the file system, other errors can be returned. The more general errors are listed here: 


EPERM 

EROFS 
EFAULT 

ENAMETOOLONG 

ENOENT 

ENOMEM 


The effective U ID does not match the owner of the file, and is not 0; or the owner or group 
were specified incorrectly. 

T he named fi le resides on a read-only file system, 
path points outside your accessible address space, 
path istoo long. 

Thefiledoes not exist. 

Insufficient kernel memory was available. 



clone 


751 


ENOTDIR 
EACCES 
ELOOP 

SEE ALSO 

chdir( 2 ) 

clone 

clone— Creates a chi Id process 

SYNOPSIS 

#include <linux/sched.h> 

#include <linux/unistd.h> 

pid t clone(void *sp, unsigned long flags); 

DESCRIPTION 

clone isan alternate interface to fork, with more options fork is equivalent to cione(0, sigcldicopyvm). 

If s P is nonzero, the child process uses s p asitsinitial stack pointer. 

The low byte of f i a gs contains the signal sent to the parent when the child dies, flags may also be bitwise ored with either or 
both of copyvm and copyfd. 

If copyvm is set, child pages are copy-on-write images of the parent pages. If copyvm is not set, the chi Id process shares the same 
pages as the parent, and both parentand child may writeon thesamedata. 

If copyfd is set, the child's file descriptors are copies of the parent'sfile descriptors. If copyfd isnot set, the chi Id's file 
descriptors are shared with the parent. 

RETURN VALUE 

On success, the PID of the child process is returned in the parent's thread of execution, and 0 is returned in the child's 
thread of execution. 0 n failure, a -1 will be returned in the parent's context, no child process will be created, and errno will 
beset appropriately. 

ERRORS 

enosys clone will always return this error, unless your kernel was compiled with 

clone_actually works_ok defined. 

eagain fork cannot allocate sufficient memory to copy the parent's page tables and allocate a task 

structure for the chi Id. 

BUGS 

By default, clone_actually_works_ok isnot defined. 

There is no entry for clone in /iib/iibc.so.4.5.26. 

Comments in the kernel as of 1.1.46 indicate that it mishandles the case where copyvm isnot set. 

SEE ALSO 

fork( 2 ) 

Linux 1.2.9,10 Junel995 


A component of the path prefix is not a directory. 

Search permission isdenied on acomponent of the path prefix, 
path contains a circular reference (that is, via a symbolic link) 


Linux 1.1.46, 21 August 1994 
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close 

close— C loses a fi le descri ptor 

SYNOPSIS 

#include <unistd.h> 
int close(int fd); 

DESCRIPTION 

close closes a file descriptor so that it no longer refers to any file and may be reused. Any locks held on the file it was 
associated with, and owned by the process, are removed (regardless of thefile descriptor that was used to obtain the lock). 

If f d is the last copy of a particular file descri ptor, the resources associated with it are freed; if the descriptor was the last 
reference to a file that has been removed using unimk, the file is deleted. 

RETURN VALUE 

close returns 0 on success, or -i if an error occurred. 

ERRORS 

ebadf fd isn't a valid open file descriptor. 

C0NF0RMST0 

SVID, AT&T, POSIX, X/OPEN , BSD 4.3 

NOTES 

N ot checking the return value of close is a common but nevertheless serious programming error. Filesystem implementa¬ 
tions that use techniques as write-behind to increase performance may lead to wri t e (2) succeeding, although the data has not 
been written yet. The error status may be reported at a later write operation, but it is guaranteed to be reported on closing 
thefile. N ot checking the return value when closing the file may lead to silent loss of data. This can especially be observed 
with N FS and disk quotas. 

SEE ALSO 

open(2), fcntl(2), shutdown(2), unlink(2), fclose(3) 

14 April 1996 


connect 

connect— Initiates a connection on a socket 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/socket.h> 

int connect(int sockfd, struct sockaddr *serv _ a d d r ,inta d d r I en); 

DESCRIPTION 

Theparametersockfd is a socket. If it is of type sock_dgram, thiscall specifies the peer with which thesocket isto be 
associated; this address is that to which datagrams are to be sent, and the only address from which datagrams are to be 
received. If thesocket is of type sock_stream, thiscall attempts to make a connection to another socket. The other socket is 



dup, dup2 



specified by serv_addr, which isan address in the communications space of the socket. Each communications space interprets 
the serv_addr, parameter in its own way. Generally, stream sockets may successfully connect only once; datagram sockets 
may use connect multiple times to change their association. Datagram sockets may dissolve the association by connecting to 
an invalid address, such as a null address. 

RETURN VALUE 

If the connection or binding succeeds, 0 is returned. On error, -1 is returned and errno is set appropriately. 

ERRORS 

See the L inux kernel source code for detai Is 

HISTORY 

The connect function call first appeared in BSD 4.2. 

SEE ALSO 

accept(2), bind(2), listen(2), socket(2), getsockname(2) 

Linux0.99.11, 23July 1993 


dup,dup2 

dup, dup2— D uplicate a file descriptor 

SYNOPSIS 

#include <unistd.h> 
int dup(int oI df d); 
int dup2(int oI df d,intnewf d); 

DESCRIPTION 

dup and dup2 create a copy of the file descriptor 0 1 df d. 

The old and new descriptors can be used interchangeably. They share locks, file position pointers and flags; for example if 
the file position is modified by using tseek on one of the descriptors the position is also changed for the other. 

Thetwo descriptors do not share the close on-exec flag, however, 
dup uses the lowest-numbered unused descriptor for the new descriptor. 
dup2 makes newt d be the copy of 01 dfd, closing lie wfd first if necessary. 

RETURN VALUE 

dup and dup2 return the new descriptor, or -1 if an error occurred (in which case errno is set appropriately). 

ERRORS 

ebadf oidfd isn't an open file descriptor, or newfd is out of the allowed range for file descriptors. 

emfile The process already hasthe maximum number of file descriptors open and tried to open a 

new one. 

WARNING 

The error returned by dup 2 is different from that returned by fcnti(.. .,f_dupfd, ...) when newfd is out of range. On some 
systemsdup 2 also sometimes returns einval like f_dupfd. 
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754 

CONFORMSTO 

SVID, AT&T, POSIX, X/OPEN , BSD 4.3 

SEE ALSO 

fcntl(2), open(2), close(2). 

Linux 1.1.46, 21 August 1994 


execve 

execve— Execute program 

SYNOPSIS 

#include <unistd.h> 

int execve (const char filename, const char *argv [], const char *e n v p [ ]); 

DESCRIPTION 

execve o executes the program pointed to by f i i ename. f i i ename must be either a binary executable or a shell script starting 
with a line in the format #1 interpreter [ arg ]. 

execve o does not return on success, and the text, data, bss, and stack of the calling process are overwritten by that of the 
program loaded. The program invoked inherits the calling process's PI D, and any open file descriptorsthat are not set to 
closeon exec. Signals pending on the parent process are cleared. 

If the current program is bei ng ptraced, a sigtrap is sent to it after a successful execvef). 

RETURN VALUE 


On success, execvef ) does not return; on error -i isreturned anderrno is set appropriately. 

ERRORS 


EACCES 

Thefileisnot a regular file. 

EACCES 

Execute permission isdenied forthefile. 

EPERM 

T he file system is mounted noexec. 

EPERM 

The file system is mounted nosui d and the file has an SUID orSGID bit set. 

E2BIG 

Theargument list istoo big. 

ENOEXEC 

Themagic number in thefile is incorrect. 

EFAULT 

fi i ename points outside your accessible address space. 

ENAMETOOLONG 

fi 1 ename iStOO long. 

ENOENT 

Thefiledoes not exist. 

ENOMEM 

Insufficientkernelmemorywasavailable. 

ENOTDIR 

A component of the path prefix is not a directory. 

EACCES 

Search permission isdenied on a component of the path prefix. 

ELOOP 

fi i ename contains a circular reference (that is, via a symbolic link). 


conforms™ 

SVID, AT&T, PO SIX, X/O PEN , BSD 4.3 

NOTES 

SUID andSGID processes can notbeptraceo'd SUID orSGID. 



fcntl 



A maximum line length of 127 characters is allowed for the first line in a #! executable shell script. This may be circum¬ 
vented by changing the max size of but, in which case you will become bound by the 1024 byte size of a buffer, which is not 
easily worked around. 

SEE ALSO 

execl(3), fork(2) 

Linux 1.1.46, 21 August 1994 


fcntl 

fcnti— M anipulatefiledescriptor 

SYNOPSIS 

#include <unistd.h> 

#include <fcntl.h> 

int fcntl(int fd,intcmd); 

int fcntl(int f d,intc md,longa r g); 


DESCRIPTION 


fcnti performs one of various miscellaneous operations on f d. The operation in question is determined by c md: 


F_DUPFD 


F_GETFD 

F_SETFD 

F_GETFL 

F_SETFL 


F_GETLK, F_SETLK, 

and f_setlkw 

F_GETLK 

F_SETLK 

F_SETLKW 

F_GET0WN 

F_SET0WN 


M akesarg be a copy of fd, closing f d first if necessary. 

T he same functionality can be more easily achieved by using dup2(2). 

The old and new descriptors may be used interchangeably. They share locks file position 
pointers, and flags; for example if the file position is modified by using lseek on one of the 
descriptors theposition is also changed fortheother. 

Thetwo descriptors do not share the close-on-exec flag, however. 

0 n success, the new descriptor is returned. 

Read the close-on-exec flag. If the low-order bit isO, the file will remain open across exec; 
otherwise it will be closed. 

Set the close-on-exec flag to the value specified by arg (only the least significant bit 
isused). 

Read the descri ptor's flags (all flags— as set by open(2) — are returned). 

Set the descriptor's flags to the value specified by a r g. 

0 nly o_append and ononblock may be set. 

Theflags are shared between copies (made with dup and so on) of the same file descriptor. 
Theflagsand their semantics are descri bed in open(2). 

M anage discretionary file locks. T he third argument arg is a pointer to a struct flock 
(that may beoverwritten by this call). 

Return theflock structure that prevents us from obtaining the lock, or set the i type field of 
thelockto fjjnlck if there isno obstruction. 

The lock is set (when i typeispjrDLCKor f_wrlck) or cleared (when it isFjjmcK). 

If the lock is held by someone else, this call returns -i and setsermo to eacces or eagain. 
LikeF_sETLK, but instead of returning an error, we wait for the lock to be released. 

G et the process ID (or process group) of the owner of a socket. 

Process groups are returned as negative values. 

Set the process or process group that owns a socket. 

For these commands, ownership means receivi ng sigio or sig-urg signals. 

Process groups are specified using negative values. 
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RETURN VALUE 

T he return value depends on the operation: 

FjjuPFD T he new descriptor. 

f_getfd Value of flag. 

f_getfl Value of flags. 

f_getown Value of descriptor owner. 

0 n error, -i is returned and errno is set appropriately. 

ERRORS 

EBADF 
EINVAL 
EMFILE 

NOTES 

The errors returned bydup 2 are different from those returned by f_dupfd. 

C0NF0RMST0 

SVID, AT&T, POSIX, X/OPEN , BSD 4.3 

SEE ALSO 

dup2(2), open(2), socket(2). 

Linux, 26 September 1995 


fd is not an open file descriptor. 

For f_dupfd, arg is negative or is greater than the maximum allowable value. 

For f_dupfd, the process already has the maximum number of file descriptors open. 


fdatasync 

fdatasync— Synchronizes a file's in-core data with that on disk 

SYNOPSIS 

#include <unistd.h> 

#ifdef POSIX SYNCHRONIZED 10 
int fdatasync(int fd); 

#endif 

DESCRIPTION 

fdatasync flushes all data buffers of a file to disk (before the system call returns). It resemblesf sync but is not required to 
update the metadata such as access time 

Applicationsthat access databases or log files often write a tiny data fragment (for example, oneline in a log file) and then 
call fsync immediately in order to ensure that the written data is physically stored on the hard disk. Unfortunately, fsync will 
always initiate two write operations: one for the newly written data and another one in order to update the modification time 
stored in the inode. If the modification time is not a part of thetransaction concept fdatasync can be used to avoid 
unnecessary inode disk write operations. 

RETURN VALUE 

0 n success, 0 is returned. 0 n error, -1 is returned and errno is set appropriately. 
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ERRORS 

ebadf fd is not a valid fi le descriptor open for writing. 

erofs, einval fd is bound to a special file which does not support synchronization. 

eio An error occurred during synchronization. 


BUGS 

Currently (Linux 1.3.86) fdatasync is equivalent to fsync. 

C0NF0RMST0 

POSIX.4 

SEE ALSO 

fsync(2), B.O. Gallmeister, POSIX.4, 0 'Reilly, pp. 220-223, 343. 


Linux 1.3.86,13 April 1996 


flock 

flock— Applies or removes an advisory lock on an open file 

SYNOPSIS 

#include <sys/file.h> 

int flock(int fd,intoperation); 

DESCRIPTION 

Apply or remove an advisory 

LOCK_SH 
LOCK_EX 
LOCKUN 
LOCK_NB 


RETURN VALUE 

0 n success, 0 is returned. 0 

ERRORS 

EWOULDBLOCK 

NOTES 

Under Linux, flock is implemented as a call to fcnti. Please see fcnti(2) for more details on errors. 

SEE ALSO 

open(2), close(2), dup(2), execve(2), fcntl(2), fork(2) 


lock on an open file. The file is specified by fd. Valid operations are given here 

Shared lock. M ore than one process may hold a shared lock for a given file at a given time. 
Exclusive lock. Only one process may hold an exclusive lock for a given file at a given time. 
Unlock. 

Don't block when locking. M ay be specified (by oring) alongwith oneof theother 
operations. 

A single file may not have both shared and exclusive locks. A file is locked (that is the 
inode), not the file descriptor. So, dup(2) and fork(2) do not create multiple instances 
of a lock. 

1 error, -i is returned and errno is set appropriately. 

The file is locked and the lock_nb flag was selected. 


Linux0.99.11, 22July 1993 
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fork,vfork 

fork, vfork— C reates a chi Id process 

SYNOPSIS 

#include <unistd.h> 
pid t fork(void); 
pid t vfork(void); 

DESCRIPTION 

fork creates a child process that differs from the parent process only in its PID and PPID, and in the fact that resource 
uti lizations are set to 0 . F ile locks and pending signals are not inherited. 

Under Linux, fork is implemented using copy-on-write pages, so the only penalties incurred by fork are the time and 
memory required to duplicate the parent's page tables and to create a unique task structure for the chi Id. 

RETURN VALUE 

On success, thePID of the child process is returned in the parent's thread of execution, and ao is returned in the child's 
thread of execution. 0 n failure, a -1 will be returned in the parent's context, no child process will be created, and errno will 
beset appropriately. 

ERRORS 

eagain fork cannot allocate sufficient memory to copy the parent's page tables and allocate a task 

structure for the child. 

BUGS 

Under Linux, vfork is merely an alias for fork, fork never returns the error enomem. 

C0NF0RMST0 

SVID, AT&T, POSIX, X/OPEN , BSD 4.3 

SEE ALSO 

clone(2), execve(2), wait(2) 

Linux 1,2.9,10 Junel995 


fsync 

fsync— Synchronizes a fi le's complete in-core state with that on disk 

SYNOPSIS 

#include <unistd.h> 
int fsync(int fd); 

DESCRIPTION 

fsync copies all in-core parts of a file to disk. 

In some applications, fdatasync isa more efficient alternative to fsync. 

RETURN VALUE 

0 n success, 0 is returned. 0 n error, -1 is returned and errno is set appropriately. 
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ERRORS 

EBADF 

EROFS, EINVAL 
EIO 

C0NF0RMST0 

POSlX.lb 

SEE ALSO 

bdflush(2), fdatasync(2), sync(2), update(8), sync(8) 

Linux 1.3.85,13 April 1996 

getdents 

getdents— Gets directory entries 

SYNOPSIS 

#include <unistd.h> 

#include <linux/dirent.h> 

#include <linux/unistd.h> 

syscall3(int, getdents, uint, fd, struct dirent *, dirp, uint, count); 
int getdents(unsigned int fd, struct dirent *dirp, unsigned int count); 

DESCRIPTION 

getdents reads several di rent structures from the directory pointed at by f d into the memory area pointed to by di rp. The 
parameter count is the size of the memory area. 

T he d i rent structure is declared as follows: 
struct dirent 

{ 

long d_ino; 
off_t d_off; 

unsigned short dreclen; 
char d name [NAME_MAX+1]; 

} 

dj no is an inode number. d_ of f is the distance from the start of the directory to the start of the next di rent. d_ reel en is the 
size of this entire di rent d_name is a null-terminated filename 

ThiSCall supersedes readdir(2). 

RETURN VALUE 

On success, the number of bytes read is returned. On end of directory, 0 is returned. On error, -1 is returned and errno is set 
appropriately. 

ERRORS 

ebadf I nvalid file descriptor f d . 

enotdir File descriptor does not refer to a directory. 

SEE ALSO 

readdin(2), readdir(3) 


/* inode number */ 

/* offset to next dirent */ 

/* length of this dirent */ 

/* file name (null-terminated) */ 


fd isnotavalid file descriptor open for writing, 
f d is bound to a special filethat does not support synchronization. 
An error occurred during synchronization. 


Linux 1.3.6, 22 July 1995 
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getdomainname,setdomainname 

getdomainname, setdomainname —G ets/SGtS domain name 

SYNOPSIS 

#include <unistd.h> 

int getdomainname(char *name, size_t I en); 
int setdomainname(const char *name, size_t len); 

DESCRIPTION 

These functions are used to access or to change the domain name of the current processor. 

RETURN VALUE 

O n success, 0 is returned. 0 n error, -1 is returned and errno isset appropriately. 

ERRORS 

EINVAL For getdomainname, name pointsto NULL or name is longer than I en. 

eperm For setdomainname, the caller was not the superuser. 

EINVAL For setdomainname, I en wastOO long. 

C0NF0RMST0 

PO SIX does not specify these calls 

BUGS 

getdomainname is not compliant with other implementations because they always return 1 en bytes, even if name is longer. 

Linux, however, returns einval in this case (as of D LL 4.4.1 libraries). 

NOTES 

Under Linux, getdomainname is implemented at the library level by calling uname(2). 

SEE ALSO 

gethostname(2), sethostname(2), uname(2) 

Linux 0.99.11 22 July 1993 


getdtablesize 

getdtabiesize— G ets descri ptor table size 

SYNOPSIS 

#include <unistd.h> 
int getdtablesize(void); 

DESCRIPTION 

getdtabiesize returns themaximum number of files a process can have open. 

NOTES 

getdtabiesize isimplemented as a library function in DLL 4.4.1. Thisfunction returns open_max (set to 256 in Linux 
0.99.11) if openjiax was defined when the library was compiled. Otherwise, -i is returned and errno isset to enosys. 
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SEE ALSO 

close(2), dup(2), open(2) 


Linux0.99.11, 22July 1993 


getgid, getegid 

getgid, getegid— Gets group identity 

SYNOPSIS 

#include <unistd.h> 
gid_t getgid(void); 
gid_t getegid(void); 

DESCRIPTION 

getgid returns the real group ID of the current process, 
getegid returns the effective group ID of the current process. 

The real ID corresponds to the ID of thecalling process. T he effective ID corresponds to the set ID bit on thefile being 
executed. 

ERRORS 

T hese functions are always successful. 

C0NF0RMST0 

POSIX, BSD 4.3 

SEE ALSO 

setregid(2), setgid(2) 

Linux0.99.11, 23July 1993 


getgroups, setgroups 

getgroups, setgroups— Get^SetS group access list 

SYNOPSIS 

#include <unistd.h> 

int getgroups(int size, gid_t Iis t [ ]); 

#define_USE_BSD 
#include <grp.h> 

int setgroups(size_t size, const gid_t ‘list); 

DESCRIPTION 

getgroups Up to si ze supplemental groups are returned in i i st . If size is e, i ist is not modified, but 

the total number of supplemental groups for the process is returned. 

Sets the supplemental groups for the process. Only the superuser may use this function. 


setgroups 
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RETURN VALUE 

getgroups 

setgroups 

ERRORS 

EFAULT 
EPERM 
EINVAL 

C0NF0RMST0 

getgroups conforms to POSIX.1 (and is present in BSD 4.3). Since setgroups requires privilege, it is not covered under 
POSIX.1. 

BUGS 

T he use bsd flag probably shouldn't be required for setgroups. 

SEE ALSO 

initgroups(3) 

Linux0.99.11, 23July 1993 


On success, the number of groups stored in list is returned (if si ze iso, however, the 
number of supplemental group IDs associated with the process is returned). 0 n error, -i is 
returned and errno is set appropriately. 

0 n success, o is returned. 0 n error, -i is returned and errno isset appropriately. 

i i st has an invalid address. 

For setgroups, theuser is not the superuser. 

For setgroups, gi d set si ze is greater than ngroups (32 for Linux 0.99.11). 



gethostid,sethostid 

gethostid, sethostid— G ets/sets the unique identifier of thecurrent host 

SYNOPSIS 

#include <unistd.h> 

long int gethostid(void); 
int sethostid(long int hostid); 

DESCRIPTION 

Get or set a unique 32-bit identifier for thecurrent machine. The 32-bit identifier is intended to be unique among all UN IX 
systemsin existence. This normally resembles the Internet address for the local machine, as returned bygethostbyname(3), 
and thus usually never needs to beset. 

T he sethostid call is restricted to the superuser. 

T he hos t i d argument is stored in thefile /etc/hostid. 

RETURN VALUES 

gethostid returns the 32-bit identifier for thecurrent host asset by sethostid(2). 

C0NF0RMST0 

POSIX.1 does not define these functions, but ISO/IEC 9945-1:1990 mentionsthem in B .4.4.1. 

FILES 


/etc/hostid 
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SEE ALSO 

hostid(l), gethostbyname(3) 


Linux 0.99.13, 29 Novemberl993 


gethostname,sethostname 

gethostname, sethostname— G ets/SGtS hostname 

SYNOPSIS 

#include <unistd.h> 

int gethostname(char *name, size_t len); 
int sethostname (const char *name, size_t len); 

DESCRIPTION 

These functions are used to accessor to change the hostname of the current processor. 

RETURN VALUE 

0 n success, 0 is returned. 0 n error, -1 is returned and errno isset appropriately. 

ERRORS 

EINVAL 

EPERM 
EFAULT 

CON FORMS TO 

POSIX.1 does not define these functions, but I SO/I EC 9945-1:1990 mentionsthem in B.4.4.1. 

BUGS 

Some other implementations of gethostname successfully return len bytes even if name is longer. Linux/Alpha complies with 
thisbehavior. Linux/i386, however, returnsEiNVAL in this case (as of D LL 4.6.27 libraries). 

NOTES 

Under Linux/Alpha, gethostname isasystem call. Under Linux/i386, gethostname isimplemented at the li brary level by 
Calling uname(2). 

SEE ALSO 

getdomainname(2), setdomainname(2), uname(2) 

Linux 1.3.6, 22 July 1995 


i en isnegativeor, for sethostname, larger than themaximum allowed size. For gethostname 
on Linux/i386, i en issmaller than the actual size. 

For sethostname, the caller was not the superuser, 
name is an invalid address. 


getitimer,setitimer 

getitimer, setitimer— Gets/sets value of an interval timer 

SYNOPSIS 


#include <sys/time.h> 

int getitimer(int which, struct itimerval *v a I u e); 

int setitimer(int whi ch,conststruct itimer-val *v a I u e, struct itimerval *o v a I u e); 
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DESCRIPTION 

Thesystem provides each process with three interval timers, each decrementing in a distinct time domain. When any timer 
expires, a signal is sent to the process, and thetimer (potentially) restarts. 

itimerreal Decrements in real time and delivers sigalrm upon expiration. 

itimervirtual D ecrements only when the process is executing, and delivers sigvtalrm upon expiration. 

itimer prof Decrements both when the process executes and when the system isexecutingon behalf of 

the process. Coupled with itimer_virtual, this timer is usually used to profile the time 
spent by the application in user and kernel space, sigprof is delivered upon expiration. 

T imer values are defi ned by the following structures: 
struct itimerval { 

struct timeval it_interval; /* next value */ 
struct timeval it_value; /* current value */ 

}; 

struct timeval { 

long tv_sec; /* seconds */ 

long tv_usec; /* microseconds */ 

}; 

getitimer(2) fills the structure indicated by vai ue with the current setting for thetimer indicated by wh i ch (one of 
itimerreal, itimervirtual, or itimerprof). The element it_vaiue is set to the amount of time remaining on the timer, or 
0 if thetimer is disabled. Similarly, it_intervai is set to the reset value. setitimer(2) sets the indicated timer to the value in 
vai ue. If oval ue is nonzero, the old value of thetimer is stored there. 

Timers decrement from i t.vai ue to 0 , generate a signal, and reset to i t ...inter vai . A timer that is set to 0 (i t.vai ue is 0 or the 
timer expires and i t ..interval is 0 ) stops. 

Both t v_s ec and t v_us ec are significant in determining the duration of atimer. 

Timers will never exp ire before the requested time, instead expiring some short, constant time afterward, dependent on the 
system timer resolution (currently 10ms). Upon expiration, a signal will be generated and thetimer reset. If thetimer expires 
while the process is active (always true for itimervirt), the signal will be delivered immediately when generated. Otherwise, 
the delivery will be offset by a small time dependent on thesystem loading. 

RETURN VALUE 

O n success, 0 is returned. 0 n error, -1 is returned and errno is set appropriately. 

ERRORS 

efault vai ue and oval ue are not valid pointers. 

einval which is not one of itimer_real, itimer_virt, or itimer_prof. 

SEE ALSO 

gettimeofday(2), sigaction(2), signal(2) 

BUGS 

Under Linux, the generation and delivery of a signal are distinct and there each signal is permitted only one outstanding 
event. It's therefore conceivable that under pathologically heavy loading, itimer_real will expire before the signal from a 
previous expiration has been delivered. Thesecond signal in such an eventwill be lost. 


Linux 0.99.11, 5 August 1993 
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getpagesize 

getpagesize— G ets system page size 

SYNOPSIS 

#include <unistd.h> 
size_t getpagesize(void); 

DESCRIPTION 

Returns the number of bytes in a page. This is the system's page size, which is not necessarily the same as the hardware page 
size. 

NOTES 

getpagesize is implemented as a library function in DLL 4.4.1. D epending on what is defined when the library iscompiled, 
this function returns exec_pagesize (set to 4096 in Linux 0.99.11), nbpg (set to 4096 in Linux 0.99.11), or nbpc (not defined in 
Linux 0.99.11 or D LL 4.4.1 libraries). 

SEE ALSO 

sbrk(2) 

Linux0.99.11, 23July 1993 


getpeername 

getpeername— G ets the name of the connected peer 

SYNOPSIS 

int getpeername(int s, struct sockaddr *name ,int*namel en); 

DESCRIPTION 

getpeername returns the name of the peer connected to sockets. Thenamei en parameter should be initialized to indicate the 
amount of space pointed to by name. On return it contains the actual size of the name returned (in bytes). The name is 
truncated if the buffer provided istoo small. 

RETURN VALUE 

O n success, 0 is returned. 0 n error, -1 is returned and errno is set appropriately. 

ERRORS 

ebadf Thearguments isnot a valid descriptor. 

enotsock Thearguments isafile, not a socket. 

enotconn The socket isnot connected. 

enobufs Insufficient resources were available in thesystem to perform the operation. 

efault The name parameter points to memory not in a valid part of the process address space. 

HISTORY 

The getpeername function call appeared in BSD 4.2. 

SEE ALSO 

accept(2), bind(2), getsockname(2) 


BSD Man Page, 24July 1993 
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getpid,getppid 

getpid, getppid— Gets process identification 

SYNOPSIS 

#include <unistd.h> 
pid_t getpid(void); 
pid_t getppid(void); 

DESCRIPTION 

getpid returns the process ID of the current process. (This is often used by routines that generate unique temporary 
filenames.) 

getppid returns the process ID of the parent of the current process. 

C0NF0RMST0 

PO SIX, BSD 4.3, SVID 

SEE ALSO 

exec(2), fork(2), kill(2), mkstemp(3), tmpnam(3), tempnam(3), tmpfile(3) 

Linux0.99.11, 23July 1993 



getpriority, setpriority 

getpriority, setpriority— Gets/sets program scheduling priority 

SYNOPSIS 

#include <sys/time.h> 

#include <sys/resource.h> 

int getpriority(int which,int who); 

int setpriority(int which,int who,int prio); 

DESCRIPTION 

The scheduling priority of the process, process group, or user, as indicated by whi c h and who, is obtained with the getpriority 
call and set with the setpriority call, whi ch is one of prio„process, PRioj 3 GRP,or priojjser, and who is interpreted relative to 
which (a process identifier for prio_process, process group identifier for prio_pgrp, and a user ID for prio_user). A 0 value of 
who denotes the current process, process group, or user, prio is a value in the range -20 to 20. The default priority is 0; lower 
priorities cause more favorable scheduling. 

The getpriority call returns the highest priority (lowest numerical value) enjoyed by any of the specified processes. The 
setpriority call setsthe priorities of all the specified processes to the specified value. Only the superuser may lower priorities. 

RETURN VALUES 

Because getpriority can legitimately return the value- 1 , it is necessary to clear the external variable errno prior to the call, 
and then check it afterward to determine whether a -1 is an error or a legitimate value. The setpriority call returns 0 if there 
is no error, or -1 if there is. 

ERRORS 

esrch N 0 process was located using thewhi ch and who values specified. 

which was not one of prioprocess, PRio_PGRP,or priojjser. 


EINVAL 



getrlimit, getrusage, se trlimit 



In addition to these errors, setpriority will fail with thefollowing: 

eperm A process was located, but neither its effective nor real user ID matched the effective user ID 

of the caller. 

eacces A nonsuperuser attempted to lower a process priority. 

HISTORY 

These function calls appeared in BSD 4.2. 

SEE ALSO 

nice(l), fork(2), renice(8) 

BSD Man Page, 24July 1993 


getrlimit, getrusage, setrlimit 

getrlimit, getrusage, setrlimit— G Gt/SGt resource limits and usage 

SYNOPSIS 

#include <sys/time.h> 

#include <sys/resource.h> 

#include <unistd.h> 

int getrlimit (int resource, struct rlimit *rlim); 

int getrusage (int who, struct rusage *usage); 

int setrlimit (int resource, const struct rlimit *rlim); 

DESCRIPTION 

getrlimit and setrlimit get and set resource limits, resource should be one of thefollowing: 

RLIMIT CPU /* CPU time in seconds */ 

RLIMIT FSIZE /* Maximum filesize */ 

RLIMIT DATA /* max data size */ 

RLIMIT STACK /* max stack size */ 

RLIMIT CORE /* max core file size */ 

RLIMIT RSS /* max resident set size */ 

RLIMIT NPROC /* max number of processes */ 

RLIMIT NOFILE /* max number of open files */ 

RLIMIT MEMLOCK /* max locked-in-memory address space*/ 

A resource may be unlimited if you set the limit to rlim_infinity. rlimit_ofile isthe BSD name for rlimit_nofile. 

T he rlimit structure is defined as follows: 

struct rlimit 

{ 

int rlim_cur; 
int rlim_max; 

}; 

getrusage returns thecurrent resource usages for awho of either rusage_self or rusage_children: 

struct rusage 

{ 

struct timeval rujjtime; /* user time used */ 
struct timeval ru_stime; /* system time used */ 
long ru_maxrss; /* maximum resident set size */ 

long ru_ixrss; /* integral shared memory size */ 
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long ru_idrss; 
long ru_isrss; 
long ru_minflt; 
long ru_majflt; 
long ru_nswap; 
long ru_inblock; 
long ru_oublock; 
long ru_msgsnd; 
long ru_msgrcv; 
long ru_nsignals; 
long ru_nvcsw; 
long ru_nivcsw; 


/* integral unshared data size */ 
/* integral unshared stack size */ 
/* page reclaims */ 

/* page faults */ 

/* swaps */ 

/* block input operations */ 

/* block output operations */ 

/* messages sent */ 

/* messages received */ 

/* signals received */ 

/* voluntary context switches */ 

/* involuntary context switches */ 


RETURN VALUE 

On success, 0 is returned. 0 n error, -1 is returned and errno is set appropriately. 

ERRORS 

EINVAL getrlimit Or setrlimit is Called With a bad resource, getrusage is Called with a bad who. 

eperm A nonsuperuser tries to use setrlimit 0 to increase the soft or hard limit above the current 

hard limit, or a superuser tries to increase rlimit_nofile above the current kernel maximum. 


C0NF0RMST0 

BSD 4.3 

SEE ALSO 

ulimit(2), quota(2) 


Linux, 23July 1993 


getsid 

getsid— Gets session ID 

SYNOPSIS 

#include <unistd.h> 
pid_t getsid(void); 

DESCRIPTION 

getsid ( 0 ) returns the session ID of the calling process, getsid(p) returns thesession ID of the process with processID p. 

ERRORS 

On error, -1 will be returned. The only error that can happen is esrch, when no processwith processID p wasfound. 

C0NF0RMST0 

Thiscall is Linux specific. 

SEE ALSO 

setsid(2) 


Linux 1.3.85,11 April 1996 
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getsockname 

getsockname — G ets socket name 

SYNOPSIS 

int getsockname(int s ", struct sockaddr *" name ", int *" namelen ); 

DESCRIPTION 

getsockname returns the current name for the specified socket. The namei en parameter should be initialized to indicate the 
amount of space pointed to byname. On return it contains the actual size of the name returned (in bytes). 

RETURN VALUE 

On success, 0 is returned. 0 n error, -1 is returned and errno isset appropriately. 

ERRORS 

ebadf Thearguments isnot a valid descriptor. 

enotsock Thearguments isafile, not a socket. 

enobufs Insufficient resources were available in thesystem to perform the operation. 

efault The name parameter points to memory not in a valid part of the process address space. 

HISTORY 

The getsockname function call appeared in BSD 4.2. 

BUGS 

N ames bound to sockets in theU NIX domain are inaccessible; getsockname returns a 0-length name. 

SEE ALSO 

bind(2), socket(2) 

BSD Man Page, 24July 1993 


getsockopt, setsockopt 

getsockopt, setsockopt— Get and set options on sockets 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/socket.h> 

int getsockopt(int s ,inti eveI ,into ptname ,void*opt val ,int*opt I en); 
int setsockopt(int s ,inti e veI ,into pt na me , const void *o p t val ,into p 11 en ); 

DESCRIPTION 

getsockopt and setsockopt manipulate theopt i ons associated with asocket. Options may exist at multiple protocol levels; 
they are always present at the uppermost socket level. 

When manipulating socket options, the level at which the option resides and the name of the option must be specified. T 0 
manipulate options at the socket level, 1 evei is specified assoi__socKET. T 0 manipulate options at any other level, the protocol 
number of the appropriate protocol controlling the option is supplied. For example, to indicate that an option isto be 
interpreted bytheTCP protocol, level should be set to the protocol number ofTCP; seegetprotoent(3). 
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The parameters opt vai and opt i en are used to access option values for setsockopt. For getsockopt the/ identify a buffer in 
which the value for the requested option(s) is to be returned. For getsockopt, opt i en is a value-result parameter, initially 
containing thesize of the buffer pointed to byoptvai , and modified on return to indicate the actual size of the value 
returned. If no option value is to be supplied or returned, opt va i may be null. 

opt name and any specified options are passed uninterpreted to the appropriate protocol module for interpretation. The 
includefile<sys/ socket. h> contains definitionsfor socket-level options, described below. 0 ptions at other protocol levels 
vary in format and name; consult the appropriate entries in section 4 of the manual. 

M ost socket-level options utilize an i nt parameter for opt vai . For setsockopt, the parameter should be nonzero to enable a 
boolean option, or 0 if the option is to be disabled. so_linger uses ast r uct linger parameter, defined in <i i nuxi socket. h>, 
which specifies the desired state of the option and the linger interval (see below). so_sndtimeo and so_rcvtimeo use a struct 
timevai parameter, defined in <sys/time.h>. 


The following options are recognized at the socket level. Except as noted, each may be examined with getsockopt and set 
with setsockopt: 


SO DEBUG 

SOJEUSEADDR 

SO_KEEPALIVE 

SO_DONTROUTE 

S0J.INGER 

S0_BR0ADCAST 

SO_OOBINLINE 

S0_SNDBUF 

S0_RCVBUF 

S0_SNDL0WAT 

S0_RCVL0WAT 

SO_SNDTIMEO 

SO JCVTIMEO 

S0_TVPE 

SO ERROR 


Enables recording of debugging information. 

E nables local address reuse. 

Enables keep connectionsalive. 

E nables routi ng bypass for outgoi ng messages. 
Linger on close if data present. 

Enables permission to transmit broadcast messages. 
Enables reception of out-of-band data in band. 

Sets buffer size for output. 

Sets buffer size for input. 

Sets minimum count for output. 

Sets minimum count for input. 

Sets time-out value for output. 

Sets time-out value for input. 

G ets the type of the socket (get only). 

G ets and clears error on the socket (get only). 


so debug enables debugging in the underlying protocol modules. 

sojieuseaddr indicates that the rules used in validating addresses supplied in abind(2) call should allow reuse of local 
addresses. 

sojeepalive enables the periodic transmission of messages on a connected socket. Should the connected party fail to 
respond to these messages, the connection is considered broken and processes using the socket are notified viaasiGPiPE 
signal when attempting to send data. 

sojontroute i ndi cates that outgoing messages should bypass the standard routing facilities. Instead, messages are directed to 
the appropriate network interface according to the network portion of the destination address. 

so_linger controls the action taken when unsent messages are queued on socket and aciose(2) is performed. If the socket 
promises reliable deli very of data and sojinger is set, the system will block the process on the close attempt until it is able to 
transmit the data or until it decides it is unable to deliver the information (a time-out period, termed the linger interval, is 
specified in the setsockopt call when sojinger is requested). If sojinger is disabled and a close is issued, the system will 
process the close i n a manner that allows the process to conti nue as quickly as possi ble. 

T he i i nge r structure is defined in <i i nux/socket. h> as follows: 
struct linger { 

int l_onoff; /* Linger active */ 

int l_linger; /* How long to linger for */ 

}; 
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i_onoff indicates whether to linger. If it is set to i, i_iinger contains the time in hundredths of seconds how long the process 
should linger to complete the close. If i_onoff is set to 0 , the process returns immediately. 

The option so^broadcast requests permission to send broadcast datagrams on the socket. Broadcast was a privileged 
operation in earlier versions of the system. With protocols that support out-of-band data, the so_oobinline option requests 
that out-of-band data be placed in the normal data input queue as received; it will then be accessible with recv or read calls 
without the msg_oob flag. Some protocols always behave as if this option is set. 

so_sndbuf and so_rcvbuf are options to adjust the normal buffer sizes allocated for output and input buffers, respectively. The 
buffer size may be increased for high-volume connections or may be decreased to limit the possible backlog of incoming data. 
Thesystem places an absolute limit on these values. 

so_sndlowat is an option to set the minimum count for output operations. M ost output operations process all of the data 
supplied by the call, delivering data to the protocol for transmission and blocking as necessary for flow control. N onblocking 
output operations will process as much data as permitted subject to flow control without blocking, but will process no data if 
flow control does not allow the smaller of the low water mark value or the entire request to be processed. A seiect(2) 
operation testing the ability to write to a socket will return true only if the low water mark amount could be processed. The 
default value for so_sndlowat is set to a convenient size for network efficiency, often 1024. 

so_rcvlowat is an option to set the minimum count for input operations. In general, receive cal Is will block until any 
(nonzero) amount of data is received, then return with the smaller of the amount avail able or the amount requested. The 
default value for so_rcvlowat is 1 . If so_rcvlowat i s set to a larger value, blocking receive calls normally wait untiI they have 
received the smaller of the low watermark value or the requested amount. Receive calls may still return less than the low 
watermark if an error occurs, a signal is caught, or the type of data next in the receive queue is different than that returned. 

so_sndtimeo is an option to set a time-out value for output operations. It accepts a struct timevai parameter with the 
number of seconds and microseconds used to limit waits for output operations to complete. If a send operation has blocked 
for this much time it returns with a partial count or with the error ewouldblock if no data were sent. In the current 
implementation, this timer is restarted each time additional data are delivered to the protocol, implying that the limit applies 
to output portions ranging in size from the low water mark to the high water mark for output. 

so_rcvtimeo is an option to set a time-out value for input operations It accepts a struct timevai parameter with the number 
of seconds and microseconds used to limit waits for input operations to complete. In thecurrent implementation, thistimer 
is restarted each timeadditional data are received by the protocol, and thusthelimitisin effect an inactivity timer. If a 
receive operation has been blocked for this much time without receiving additional data, it returns with a short count or with 
the error ewouldblock if no data were received. 

Finally, so_type and so_error are options used only with setsockopt. 

so_type returns the type of the socket, such as sock_stream; it is useful for servers that inherit sockets on startup. 

so_error returns any pending error on the socket and clears the error status. It may be used to check for asynchronous errors 
on connected datagram sockets or for other asynchronous errors. 

RETURN VALUE 

On success, 0 is returned. 0 n error, -1 is returned and errno is set appropriately. 

ERRORS 

ebadf Thearguments isnot a valid descriptor. 

enotsock Thearguments isafile, not a socket. 

enoprotoopt Theoption isunknown at the level indicated. 

efault The address pointed to by 0 p t v a 1 isnot in a valid part of the process address space. For 

getsockopt, this error may also be returned if optlen isnot in a valid part of the process 
address space. 
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HISTORY 

These system calls appeared in BSD 4.2. 

BUGS 

Sa/eral of the socket options should be handled at lower levels of the system. 

SEE ALSO 

ioctl(2), socket(2), getprotoent(3), protocols(5) 

BSD M an Page, 22 April 1996 

gettimeofday, settimeofday 

gettimeofday, settimeof day—Get/set time 

SYNOPSIS 

#include <sys/time.h> 

#include <unistd.h> 

int gettimeofday(struct timeval *tv, struct timezone *tz); 

int settimeofday(const struct timeval *tv , const struct timezone *tz); 

DESCRIPTION 

gettimeofday and settimeof day Can Set the time 3S well as a timezone. t v is a timeval struct, as Specified in /usr/include/ 
sys/time.h: 

struct timeval { 

long tv_sec; /* seconds */ 

long tv_usec; /* microseconds */ 

}; 

and tz is a timezone: 

struct timezone { 

int tzjninuteswest; 

/* minutes west of Greenwich */ 
int tz_dsttime; 

/* type of dst correction */ 

}; 

with daylight savings times defined as follows: 

DST_NONE /* not on dst */ 

DSTJJSA /* USA style dst */ 

DST_AUST /* Australian style dst */ 

DST_WET /* Western European dst */ 

DSTJVIET /* Middle European dst */ 

DST_EET /* Eastern European dst */ 

DST_CAN /* Canada */ 

DST_GB /* Great Britain and Eire */ 

DST_RUM /* Rumania */ 

DST_TUR /* Turkey */ 

DST_AUSTALT /* Australian style with shift in 1986 */ 
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And thefollowing macros are defined to operateon this: 

#define timerisset(tvp)\ 

((tvp)->tv_sec || (tvp)->tv_usec) 

#define timercmp(tvp, uvp, cmp)\ 

((tvp)->tv_sec cmp (uvp)->tv_sec ||\ 

(tvp)->tv_sec == (uvp)->tv_sec &&\ 

(tvp)->tv_usec cmp (uvp)->tv_usec) 

#define timerclear(tvp) 

((tvp)->tv_sec = (tvp)->tv_usec = 0) 

If either tv or t z is null, the corresponding structure is not set or returned. 

Only the superuser can use settimeofday. 


ERRORS 

eperm settimeofday is called by someone other than the superuser. 

einval Timezone(orsomethingelse) isinvalid. 

C0NF0RMST0 

BSD 4.3 


SEE ALSO 

date(l), adjtimex(2), time(2), ctime(3), ftime(3) 


Linux 1.2.4,15 April 1995 


getuid, geteuid 

getuid, geteuid— Get user identity 

SYNOPSIS 

#include <unistd.h> 
uid_t getuid(void); 
uid_t geteuid(void); 

DESCRIPTION 

getuid returns the real user ID of the current process, 
geteuid returns the effective user ID of the current process. 

The real ID corresponds to the ID of the calling process. The effective ID corresponds to the set ID bit on thefile being 
executed. 

ERRORS 

T hese functions are always successful. 

C0NF0RMST0 

POSIX, BSD 4.3 

SEE ALSO 

setreuid(2), setuid(2) 


Linux0.99.11, 23July 1993 
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idle 

idle— M akes process 0 idle 

SYNOPSIS 

#include <unistd.h> 
void idle(void); 

DESCRIPTION 

idle is an internal system call used during bootstrap. It marks the process's pages as swappable lowers its priority, and enters 
the main scheduling loop, idle never returns. 

Only process 0 may call idle. Any user process, even a process with superuser permission, will receiveEPERM. 

RETURN VALUE 

idle never returnsfor process 0, and always returns-i for a user process. 

ERRORS 

eperm Always, for a user process. 

Linux 1.1.46, 21 August 1994 


ioctl 

iocti— Controls devices 

SYNOPSIS 

#include <sys/ioctl.h> 

int ioctl(int d,intr equest , ...); 

(The "third" argument istraditionally char *ar gp and will be so named for this discussion.) 

DESCRIPTION 

The iocti function manipulates the underlying device parameters of special files. In particular, many operating characteris¬ 
tics of character special files (for example, terminals) may be controlled with iocti requests. The argument d must bean open 
file descriptor. 

An iocti repest has encoded in it whether theargument is an i n parameter or out parameter, and thesizeof theargument 
a r gp in bytes. M acrosand defines used in specifying an iocti request are located in the file <sys / i octi. h>. 

RETURN VALUE 

O n success, e is returned. 0 n error, -i is returned and errno isset appropriately. 

ERRORS 

ebadf d is not a valid descriptor. 

enotty d is not associated with a character special device 

enotty The specified request does not apply to the kind of object that the descriptor d references. 

EINVAL request Or a r g p isnotvalid. 

HISTORY 

An iocti function call appeared in version 7 AT&T UNIX. 
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SEE ALSO 

execve(2), fcntl(2), mt(4), sd(4), tty(4) 

INTRODUCTION 

This is iocti List 1.3.27, a list of iocti calls in Linux/i386 kernel 1.3.27. It contains 421 ioctisfrom /usr/inciude/ 
fasm,linuxg/* .h. For each iocti, you'll find the numerical value name, and argument type. 

An argument type of const struct too * meansthe argument is input to the kernel, struct too * means the kernel outputs 
theargument. I f the kernel uses the argument for both input and output, thisis marked with // i-o. 

Some ioctis take more arguments or return more values than a single structure. These are marked // more and are docu¬ 
mented further in a separate section. 

T his list is incomplete. 11 does not include 

■ ioctis defined internal to the kernel (scsi iocti.h). 

■ ioctis defined in modules distributed separately from the kernel. 

And, of course, I may have errors and omissions. 

Please e-mail changes and comments to mecMuracef .shout.net. I am particularly interested in loadable modules that define 
their own ioctis. If you know of such a module tell me where I can ftp it, and I'll include its ioctis in my next release. 

MAIN TABLE 


<i ncI ude/ asm- i 3 8 6/ socket. h> 


0X00008901 

FIOSETOWN 

const int * 

0X00008902 

SIOCSPGRP 

const int * 

0X00008903 

FIOGETOWN 

int * 

0X00008904 

SIOCGPGRP 

int * 

0X00008905 

SIOCATMARK 

int * 

0X00008906 

SIOCGSTAMP 

timeval * 

ic 1 ude/ asm- i 3 8 6 / 1 er mi os. h> 

0X00005401 

TCGETS 

struct termios * 

0X00005402 

TCSETS 

const struct termios * 

0X00005403 

TCSETSW 

const struct termios * 

0X00005404 

TCSETSF 

const struct termios * 

0X00005405 

TCGETA 

struct termio * 

0x00005406 

TCSETA 

const struct termio * 

0X00005407 

TCSETAW 

const struct termio * 

0X00005408 

TCSETAF 

const struct termio * 

0X00005409 

TCSBRK 

int 

0X0000540A 

TCXONC 

int 

0X0000540B 

TCFLSH 

int 

0X0000540C 

TIOCEXCL 

void 

0X0000540D 

TIOCNXCL 

void 

0X0000540E 

TIOCSCTTY 

int 

0X0000540F 

TIOCGPGRP 

pid_t * 

0X00005410 

TIOCSPGRP 

const pid_t * 
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<i ncI ude/ asm- i 3 8 6 / 1 er mi os, h> 


0X00005411 

TIOCOUTQ 

int * 

0X00005412 

TIOCSTI 

const char * 

0X00005413 

TIOCGWINSZ 

const struct winsize * 

0X00005414 

TIOCSWINSZ 

struct winsize * 

0X00005415 

TIOCMGET 

int * 

0x00005416 

TIOCMBIS 

const int * 

0x00005417 

TIOCMBIC 

const int * 

0x00005418 

TIOCMSET 

const int * 

0x00005419 

TIOCGSOFTCAR 

int * 

0X0000541A 

TIOCSSOFTCAR 

const int * 

0x0000541B 

FIONREAD 

int * 

0x0000541B 

TIOCINQ 

int * 

0x0000541C 

TIOCLINUX 

const char * 

0x0000541D 

TIOCCONS 

void 

0x0000541E 

TIOCGSERIAL 

struct serial_strucct * 

0x0000541F 

TIOCSSERIAL 

const struct serial_strucct * 

0X00005420 

TIOCPKT 

const int * 

0X00005421 

FIONBIO 

const int * 

0X00005422 

TIOCNOTTY 

void 

0X00005423 

TIOCSETD 

const int * 

0X00005424 

TIOCGETD 

int * 

0X00005425 

TCSBRKP 

int 

0X00005426 

TIOCTTYGSTRUCT 

struct tty_strucct * 

0x00005450 

FIONCLEX 

void 

0X00005451 

FIOCLEX 

void 

0X00005452 

FIOASYNC 

const int * 

0X00005453 

TIOCSERCONFIG 

void 

0X00005454 

TIOCSERGWILD 

int * 

0X00005455 

TIOCSERSWILD 

const int * 

0x00005456 

TIOCGLCKTRMIOS 

struct termios * 

0x00005457 

TIOCSLCKTRMIOS 

const struct temios * 

0x00005458 

TIOCSERGSTRUCT 

struct async_strucct * 

0x00005459 

TIOCSERGETLSR 

int * 

0X0000545A 

TIOCSERGETMULTI 

struct serial_multiport_strucct * 

0X0000545B 

TIOCSERSETMULTI 

const struct serial_multiport_strucct * 

icl ude/1 i nux/ ax25. h> 

0X000089E0 

SI0CAX25GETUID 

const struct sockaddr_ax25 * 

0X000089E1 

SI0CAX25ADDUID 

const struct sockaddr_ax25 * 

0X000089E2 

SI0CAX25DELUID 

const struct sockaddr_ax25 * 

0X000089E3 

SI0CAX25N0UID 

const int * 



<i ncI ude/1 i nux/ ax25. h> 



0X00002001 
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const int * 

struct ax25_parms_strucct * // 1-0 
const struct ax25_parms-struct * 


void 

void 

void 

void 


void 

void 

const struct cdromjnsf * 

const struct cdrom_ti * 

struct cdrom_tochdr * 

struct cdrom_tocentry *// 1-0 

void 

void 

void 

const struct cdrom_volctrl * 
struct cdrom_subchnl * // 1-0 
const struct cdromjnsf * // MORE 
const struct cdromjnsf * // MORE 
const struct cdrom_read_audio * 

SW int 

struct cdrom_multisession * // 1-0 

struct f char [8]; g * 

void 

struct cdrom_volctrl * 
const struct cdromjnsf * // MORE 
const struct cdromjnsf * // MORE 
const struct cdrom msf * 


int 

int 
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<i ncI ude/1 i nux/ cycl ades. h> 


0x00435901 

CYGETMON 

struct cycladesjnonitor * 

0x00435902 

CYGETTHRESH 

int * 

0x00435903 

CYSETTHRESH 

int 

0x00435904 

CYGETDEFTHRESH 

int * 

0x00435905 

CYSETDEFTHRESH 

int 

0x00435906 

CYGETTIMEOUT 

int * 

0x00435907 

CYSETTIMEOUT 

int 

0x00435908 

CYGETDEFTIMEOUT 

int * 

0x00435909 

CYSETDEFTIMEOUT 

int 

icl ude/1 i nux/ ext 2 f s. h> 

0x80046601 

EXT2_I0C_GETFLAGS 

int * 

0x40046602 

EXT2_I0C_SETFLAGS 

const int * 

0x80047601 

EXT2_I0C_GETVERSI0N 

int * 

0x40047602 

EXT2_I0C_SETVERSI0N 

const int * 

icl ude/ii nux/fd. h> 

0X00000000 

FDCLRPRM 

void 

0x00000001 

FDSETPRM 

const struct floppy_struct * 

0X00000002 

FDDEFPRM 

const struct floppy_struct * 

0X00000003 

FDGETPRM 

struct floppy_struct * 

0X00000004 

FDMSGON 

void 

0X00000005 

FDMSGOFF 

void 

0X00000006 

FDFMTBEG 

void 

0X00000007 

FDFMTTRK 

const struct format_descr * 

0X00000008 

FDFMTEND 

void 

0X0000000A 

FDSETEMSGTRESH 

int 

0X0000000B 

FDFLUSH 

void 

0X0000000C 

FDSETMAXERRS 

const struct floppy_max_errors * 

0X0000000E 

FDGETMAXERRS 

struct floppy_max_errors * 

0X00000010 

FDGETDRVTYP 

struct f char [16] ; g * 

0x00000014 

FDSETDRVPRM 

const struct floppy_drive_params * 

0x00000015 

FDGETDRVPRM 

struct floppyjirive_params * 

0X00000016 

FDGETDRVSTAT 

struct floppy_drive_struct * 

0x00000017 

FDPOLLDRVSTAT 

struct floppyj1rive_struct * 

0X00000018 

FDRESET 

int 

0x00000019 

FDGETFDCSTAT 

struct floppy_fdc_state * 

0X0000001B 

FDWERRORCLR 

void 

0X0000001C 

FDWERRORGET 

struct floppy_write_errors * 

0x0000001E 

FDRAWCMD 

struct floppy_raw_cmd * // MORE // 1-0 

0X00000028 

FDTWADDLE 

void 



<i n c I u d e /1 i nux/fs. h> 
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0X0000125D 

BLKROSET 

const int * 

0X0000125E 

BLKROGET 

int * 

0X0000125F 

BLKRRPART 

void 

0x00001260 

BLKGETSIZE 

int * 

0x00001261 

BLKFLSBUF 

void 

0x00001262 

BLKRASET 

int 

0x00001263 

BLKRAGET 

int * 

0X00000001 

FIBMAP 

int * // 1-0 

0X00000002 

FIGETBSZ 

int * 

<i nc 1 ude/1 i nux/hdreg. h> 

0X00000301 

HDIO_GETGEO 

struct hd geometry * 

0X00000302 

HDIO_GET_UNMASKINTR 

int * 

0x00000304 

HDIO_GET_MULTCOUNT 

int * 

0X00000307 

HDIO_GET_IDENTITY 

struct hd driveid * 

0X00000308 

HDIO_GET_KEEPSETTINGS 

int * 

0X00000309 

HDIO_GET_CHIPSET 

int * 

0X0000030A 

HDIO_GET_NOWERR 

int * 

0X0000030B 

HDIO_GET_DMA 

int * 

0x0000031F 

HDIO_DRIVE_CMD 

int * II 1-0 

0x00000321 

HDIO_SET_MULTCOUNT 

int 

0X00000322 

HDIO_SET_UNMASKINTR 

int 

0x00000323 

HDIO_SET_KEEPSETTINGS 

int 

0x00000324 

HDIO_SET_CHIPSET 

int 

0x00000325 

HDIO_SET_NOWERR 

int 

0x00000326 

HDIO SET_DMA 

int 


<i n c I u d e /1 i n u x / i f e q I . h > 


0X000089F0 

EQL_ENSLAVE 

struct 

ifreq 

* 

II 

MORE 

ii 

1-0 

0X000089F1 

EQL_EMANCIPATE 

struct 

ifreq 

* 

II 

MORE 

ii 

1-0 

0X000089F2 

EQL_GETSLAVECFG 

struct 

ifreq 

* 

II 

MORE 

ii 

1-0 

0X000089F3 

EQL_SETSLAVECFG 

struct 

ifreq 

* 

II 

MORE 

ii 

1-0 

0X000089F4 

EQL_GETMASTRCFG 

struct 

ifreq 

* 

II 

MORE 

ii 

1-0 

0X000089F5 

EQL_SETMASTRCFG 

struct 

ifreq 

* 

II 

MORE 

ii 

1-0 


<i ncI ude/1 i nux/ i f pi i p. h> 


struct ifreq * // 1-0 


0X000089F0 


SIOCDEVPLIP 
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<i nc 1 ude/1 i nux/ i f ppp. h> 

0x00005490 

PPPIOCGFLAGS 

int * 

0X00005491 

PPPIOCSFLAGS 

const int * 

0X00005492 

PPPIOCGASYNCMAP 

int * 

0X00005493 

PPPIOCSASYNCMAP 

const int * 

0X00005494 

PPPIOCGUNIT 

int * 

0X00005495 

PPPIOCSINPSIG 

const int * 

0X00005497 

PPPIOCSDEBUG 

const int * 

0X00005498 

PPPIOCGDEBUG 

int * 

0x00005499 

PPPIOCGSTAT 

struct ppp_stats * 

0X0000549A 

PPPIOCGTIME 

struct ppp_ddinfo * 

0X0000549B 

PPPIOCGXASYNCMAP 

struct f int [8]; g * 

0X0000549C 

PPPIOCSXASYNCMAP 

const struct f int [8]; g * 

0X0000549D 

PPPIOCSMRU 

const int * 

0X0000549E 

PPPIOCRASYNCMAP 

const int * 

0X0000549F 

PPPIOCSMAXCID 

const int * 

<i nc 1 ude/1 i nux/i px. h> 

0X000089E0 

SIOCAIPXITFCRT 

const char * 

0X000089E1 

SIOCAIPXPRISLT 

const char * 

0X000089E2 

SIOCIPXCFGDATA 

struct ipx_config_data * 

<i n c 1 u d e / linux/kd.h> 

0X00004B60 

GIO_FONT 

struct f char [8192]; g * 

0X00004B61 

PIO_FONT 

const struct f char [8192]; g * 

0X00004B6B 

GIO_FONTX 

struct console_font_desc * // MORE 1-0 

0X00004B6C 

PIO_FONTX 

const struct console_font_desc * //MORE 

0X00004B70 

GIO_CMAP 

struct f char [48]; g * 

0X00004B71 

PIO_CMAP 

const struct f char [48]; g 

0X00004B2F 

KIOCSOUND 

int 

0X00004B30 

KDMKTONE 

int 

0X00004B31 

KDGETLED 

char * 

0X00004B32 

KDSETLED 

int 

0X00004B33 

KDGKBTYPE 

char * 

0X00004B34 

KDADDIO 

int // MORE 

0X00004B35 

KDDELIO 

int // MORE 

0X00004B36 

KDENABIO 

void // MORE 

0X00004B37 

KDDISAB10 

void // MORE 

0X00004B3A 

KDSETMODE 

int 

0X00004B3B 

KDGETMODE 

int * 

0X00004B3C 

KDMAPDISP 

void // MORE 
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0X00004B3D 

KDUNMAPDISP 

void // MORE 

0X00004B40 

GIO_SCRNMAP 

struct f char [ETABSZ]; g * 

0X00004B41 

PIO_SCRNMAP 

const struct f char [E_TABSZ] ; g * 

0X00004B69 

GIOJJNISCRNMAP 

struct f short [ E TABSZ]; g * 

0X00004B6A 

PIOJJNISCRNMAP 

const struct f short [ E_T ABSZ]; g * 

0X00004B66 

GIOJJNIMAP 

struct unimapdesc * II MORE // 1-0 

0X00004B67 

PIOJJNIMAP 

const struct unimapdesc * // MORE 

0X00004B68 

PIOJJNIMAPCLR 

const struct unimapinit * 

0X00004B44 

KDGKBMODE 

int * 

0X00004B45 

KDSKBMODE 

int 

0X00004B62 

KDGKBMETA 

int * 

0X00004B63 

KDSKBMETA 

int 

0X00004B64 

KDGKBLED 

int * 

0X00004B65 

KDSKBLED 

int 

0X00004B46 

KDGKBENT 

struct kbentry * // 1-0 

0X00004B47 

KDSKBENT 

const struct kbentry * 

0X00004B48 

KDGKBSENT 

struct kbsentry * // 1-0 

0X00004B49 

KDSKBSENT 

const struct kbsentry * 

0X00004B4A 

KDGKBDIACR 

struct kbdiacrs * 

0X00004B4B 

KDSKBDIACR 

const struct kbdiacrs * 

0X00004B4C 

KDGETKEYCODE 

struct kbkeycode * // 1-0 

0X00004B4D 

KDSETKEYCODE 

const struct kbkeycode * 

0X00004B4E 

KDSIGACCEPT 

int 

ul ude/1 i nux/1 p. h> 

0X00000601 

LPCHAR 

int 

0X00000602 

LPTIME 

int 

0X00000604 

LPABORT 

int 

0X00000605 

LPSETIRQ 

int 

0X00000606 

LPGETIRQ 

int * 

0X00000608 

LPWAIT 

int 

0X00000609 

LPCAREFUL 

int 

0X0000060A 

LPABORTOPEN 

int 

0X0000060B 

LPGETSTATUS 

int * 

0X0000060C 

LPRESET 

void 

0X0000060D 

LPGETSTATS 

struct lp stats * 

icl ude/l i nux / mroute. h> 

0X000089E0 

SIOCGETVIFCNT 

struct sioc_vif_req * // 1-0 

0X000089E1 

SIOCGETSGCNT 

struct sioc_sg_req * // 1-0 
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0X40086D01 

MTIOCTOP 

const struct mtop * 

0x801C6D02 

MTIOCGET 

struct mtget * 

0X80046D03 

MTIOCPOS 

struct mtpos * 

0X80206D04 

MTIOCGETCONFIG 

struct mtconfiginfo * 

0X40206D05 

MTIOCSETCONFIG 

const struct mtconfiginfo * 

<i ncl ude/1 i nux/ net rom. h> 

0X000089E0 

SIOCNRGETPARMS 

struct nr_parms_struct * // 1-0 

0X000089E1 

SIOCNRSETPARMS 

const struct nr_parms_struct * 

0X000089E2 

SIOCNRDECOBS 

void 

0X000089E3 

SIOCNRRTCTL 

const int * 

<i ncl ude/1 i nux/sbpcd. h> 

0X00009000 

DDIOCSDBG 

const int * 

0X00005382 

CDROMAUDIOBUFSIZ 

int 

<i ncl ude/1 i nux/see. h> 

0X00005470 

TIOCSCCINI 

void 

0X00005471 

TIOCCHANINI 

const struct sccjnodem * 

0X00005472 

TIOCGKISS 

struct ioctl_command * // 1-0 

0X00005473 

TIOCSKISS 

const struct ioctl_command * 

0X00005474 

TIOCSCCSTAT 

struct scc_stat * 

<i ncl ude/1 i nux/scsi. h> 

0x00005382 

SCSI_IOCTL_GET_IDLUN 

struct f int [2]; g * 

0x00005383 

SCSI_IOCTL_TAGGED_ENABLE 

void 

0x00005384 

SCSI_IOCTL_TAGGED_DISABLE 

void 

0x00005385 

SCSI_IOCTL_PROBE_HOST 

const int * // MORE 

<i ncl ude/1 i nux/ smb f s . h> 

0x80027501 

SMB_IOC_GETMOUNTUID 

uid t * 

<i ncl ude/1 i nux/socki os. h> 

0X0000890B 

SIOCADDRT 

const struct rtentry * // MORE 

0X0000890C 

SIOCDELRT 

const struct rtentry * // MORE 

0x00008910 

SIOCGIFNAME 

char [] 

0x00008911 

SIOCSIFLINK 

void 

0x00008912 

SIOCGIFCONF 

struct ifeonf * // MORE // 1-0 

0x00008913 

SIOCGIFFLAGS 

struct ifreq *111-0 

0x00008914 

SIOCSIFFLAGS 

const struct ifreq * 
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0X00008915 

SIOCGIFADDR 

struct ifreq * // 1-0 

0x00008916 

SIOCSIFADDR 

const struct ifreq * 

0x00008917 

SIOCGIFDSTADDR 

struct ifreq * // 1-0 

0x00008918 

SIOCSIFDSTADDR 

const struct ifreq * 

0x00008919 

SIOCGIFBRDADDR 

struct ifreq *II 1-0 

0x0000891 A 

SIOCSIFBRDADDR 

const struct ifreq * 

0x0000891B 

SIOCGIFNETMASK 

struct ifreq * // 1-0 

0x0000891C 

SIOCSIFNETMASK 

const struct ifreq * 

0x0000891D 

SIOCGIFMETRIC 

struct ifreq * // 1-0 

0x0000891E 

SIOCSIFMETRIC 

const struct ifreq * 

0x0000891F 

SIOCGIFMEM 

struct ifreq * // 1-0 

0x00008920 

SIOCSIFMEM 

const struct ifreq * 

0x00008921 

SIOCGIFMTU 

struct ifreq * // 1-0 

0x00008922 

SIOCSIFMTU 

const struct ifreq * 

0x00008923 

OLD SIOCGIFHWADDR 

struct ifreq * // 1-0 

0x00008924 

SIOCSIFHWADDR 

const struct ifreq * // MORE 

0x00008925 

SIOCGIFENCAP 

int * 

0x00008926 

SIOCSIFENCAP 

const int * 

0x00008927 

SIOCGIFHWADDR 

struct ifreq * // 1-0 

0x00008929 

SIOCGIFSLAVE 

void 

0X00008930 

SIOCSIFSLAVE 

void 

0X00008931 

SIOCADDMULTI 

const struct ifreq * 

0x00008932 

SIOCDELMULTI 

const struct ifreq * 

0X00008940 

SIOCADDRTOLD 

void 

0X00008941 

SIOCDELRTOLD 

void 

0X00008950 

SIOCDARP 

const struct arpreq * 

0X00008951 

SIOCGARP 

struct arpreq * II 1-0 

0X00008952 

SIOCSARP 

const struct arpreq * 

0X00008960 

SIOCDRARP 

const struct arpreq * 

0X00008961 

SIOCGRARP 

struct arpreq * II 1-0 

0x00008962 

SIOCSRARP 

const struct arpreq * 

0X00008970 

SIOCGIFMAP 

struct ifreq * // 1-0 

0X00008971 

SIOCSIFMAP 

const struct ifreq * 

icl ude/1 i nux/ soundcard. h> 

0X00005100 

SNDCTL_SEQ_RESET 

void 

0X00005101 

SNDCTL_SEQ_SYNC 

void 

0XC08C5102 

SNDCTL_SYNTH_INFO 

struct synth_info *111-0 

0XC0045103 

SNDCTL_SEQ_CTRLRATE 

int * // 1-0 

0x80045104 

SNDCTL_SEQ_GETOUTCOUNT 

int * 

0x80045105 

SNDCTL_SEQ_GETINCOUNT 

int * 

0x40045106 

SNDCTL_SEQ_PERCMODE 

void 
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0x40285107 

SNDCTL FM LOAD INSTR 

const struct sbi_instrument 

0x40045108 

SNDCTL_SEQ_TESTMIDI 

const int * 

0x40045109 

SNDCTL_SEQ_RESETSAMPLES 

const int * 

0x8004510A 

SNDCTL_SEQ_NRSYNTHS 

int * 

0x8004510B 

SNDCTL_SEQ_NRMIDIS 

int * 

0XC074510C 

SNDCTL_MIDI_INFO 

struct midi_info * // 1-0 

0x4004510D 

SNDCTL_SEQ_THRESHOLD 

const int * 

0XC004510E 

SNDCTL_SYNTH_MEMAVL 

int * // 1-0 

0x4004510F 

SNDCTL_FM_40P_ENABLE 

const int * 

0XCFB85110 

SNDCTL_PMGR_ACCESS 

struct patmgr_info * // 1-0 

0x00005111 

SNDCTL_SEQ_PANIC 

void 

0x40085112 

SNDCTL_SEQ_OUTOFBAND 

const struct seq_event_rec : 

0XC0045401 

SNDCTL_TMR_TIMEBASE 

int * // 1-0 

0x00005402 

SNDCTL_TMR_START 

void 

0x00005403 

SNDCTL_TMR_STOP 

void 

0X00005404 

SNDCTL_TMR_CONTINUE 

void 

0XC0045405 

SNDCTL_TMR_TEMPO 

int * // 1-0 

0XC0045406 

SNDCTL_TMR_SOURCE 

int * // 1-0 

0x40045407 

SNDCTL_TMR_METRONOME 

const int * 

0x40045408 

SNDCTL_TMR_SE LECT 

int * // 1-0 

0XCFB85001 

SNDCTL_PMGR_IFACE 

struct patmgr_info * // 1-0 

0XC0046D00 

SNDCTL_MIDI_PRETIME 

int * // 1-0 

0XC0046D01 

SNDCTL_MIDI_MPUMODE 

const int * 

0XC0216D02 

SNDCTL_MIDI_MPUCMD 

struct mpu_command_rec * // 

0X00005000 

SNDCTL_DSP_RESET 

void 

0X00005001 

SNDCTL_DSP_SYNC 

void 

0XC0045002 

SNDCTL_DSP_SPEED 

int * // 1-0 

0XC0045003 

SNDCTL_DSP_STEREO 

int * // 1-0 

0XC0045004 

SNDCTL_DSP_GETBLKSIZE 

int * // 1-0 

0XC0045006 

SOUND_PCM_WRITE CHANNELS 

int * // 1-0 

0XC0045007 

SOUND_PCM_WRITE FILTER 

int * // 1-0 

0x00005008 

SNDCTL_DSP_POST 

void 

0XC0045009 

SNDCTL_DSP_SUBDIVIDE 

int * // 1-0 

0XC004500A 

SNDCTL_DSP_SETFRAGMENT 

int * // 1-0 

0X8004500B 

SNDCTL_DSP_GETFMTS 

int * 

0XC0045005 

SNDCTL_DSP_SETFMT 

int * // 1-0 

0X800C500C 

SNDCTL_DSP_GETOSPACE 

struct audio-buf-info * 

0X800C500D 

SNDCTL_DSP_GETISPACE 

struct audio-buf-info * 

0X0000500E 

SNDCTL_DSP_NONBLOCK 

void 

0x80045002 

SOUND_PCM_READ RATE 

int * 

0x80045006 

SOUND_PCM_READ CHANNELS 

int * 

0x80045005 

SOUND_PCM_READ BITS 

int * 
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0x80045007 

SOUND_PCM_READ FILTER 

int * 


0X00004300 

SNDCTL_COPR_RESET 

void 


0XCFB04301 

SNDCTL_COPR_LOAD 

const 

struct copr_buffer * 

0XC0144302 

S N DCT L_CO P R_R DAT A 

struct 

copr_debug_buf * II 

0xC0144303 

SNDCTL_COPR_RCODE 

struct 

copr_debug_buf * II 

0x40144304 

S N DCT L_CO P R_WDAT A 

const 

struct copr_debug_buf 

0x40144305 

SNDCTL_COPR_WCODE 

const 

struct copr_debug_buf 

0xC0144306 

SNDCTL_COPR_RUN 

struct 

copr_debug_buf * II 

0xC0144307 

SNDCTL_COPR_HALT 

struct 

copr_debug_buf * II 

0X4FA44308 

SNDCTL_COPR_SENDMSG 

const 

struct copr_msg * 

0X8FA44309 

SNDCTL_COPR_RCVMSG 

struct 

coprjnsg * 

0X80044D00 

SOUND_MIXER_READ_VOLUME 

int * 


0X80044D01 

SOUND_MIXER_READ_BASS 

int * 


0X80044D02 

SOUND_MIXER_READ_TREBLE 

int * 


0X80044D03 

SOUND_MIXER_READ_SYNTH 

int * 


0X80044D04 

SOUND_MIXER_READ_PCM 

int * 


0X80044D05 

SOU N D_MIX E R_R EAD_S P EAKE R 

int * 


0X80044D06 

SOUND_MIXER_READ_LINE 

int * 


0X80044D07 

SOUND_MIXER_READ_MIC 

int * 


0X80044D08 

SOUND_MIXER_READ_CD 

int * 


0X80044D09 

SOUND_MIXER_READ_IMIX 

int * 


0X80044D0A 

SOUND_MIXER_READ_ALTPCM 

int * 


0X80044D0B 

SOUND_MIXER_READ_RECLEV 

int * 


0X80044D0C 

SOUND_MIXER_READ_IGAIN 

int * 


0X80044D0D 

SOUND_MIXER_READ_OGAIN 

int * 


0X80044D0E 

SOUND_MIXER_READ_LINE1 

int * 


0X80044D0F 

S0UND_MIXER_READ_LINE2 

int * 


0X80044D10 

S0UND_MIXER_READ_LINE3 

int * 


0X80044D1C 

SOUND_MIXER_READ_MUTE 

int * 


0X80044D1D 

SOUND_MIXER_READ_ENHANCE 

int * 


0X80044D1E 

SOUND_MIXER_READ_LOUD 

int * 


0X80044DFF 

SOUND_MIXER_READ_RECSRC 

int * 


0X80044DFE 

SOUND_MIXER_READ_DEVMASK 

int * 


0X80044DFD 

SOUND_MIXER_READ_RECMASK 

int * 


0X80044DFB 

SOUND_MIXER_READ_STEREODEVS 

int * 


0X80044DFC 

SOUND_MIXER_READ_CAPS 

int * 


0XC0044D00 

SOUND_MIXER_WRITE_VOLUME 

int * 

II 1-0 

0XC0044D01 

SOUND_MIXER_WRITE_BASS 

int * 

II 1-0 

0XC0044D02 

SOUND_MIXER_WRITE_TREBLE 

int * 

II 1-0 

0XC0044D03 

SOUND_MIXER_WRITE_SYNTH 

int * 

II 1-0 

0XC0044D04 

SOUND_MIXER_WRITE_PCM 

int * 

II 1-0 

0XC0044D05 

SOUND_MIXER_WRITE_SPEAKER 

int * 

II 1-0 
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0XC0044D06 


SOUND_MIXER_WRITE_LINE 

int * // 1-0 

0XC0044D07 


SOUND_MIXER_WRITE_MIC 

int * // 1-0 

0XC0044D08 


SOUND_MIXER_WRITE_CD 

int * // 1-0 

0XC0044D09 


SOUND_MIXER_WRITE_IMIX 

int * // 1-0 

0XC0044D0A 


SOUND_MIXER_WRITE_ALTPCM 

int * // 1-0 

0XC0044D0B 


SOUND_MIXER_WRITE_RECLEV 

int * II 1-0 

0XC0044D0C 


SOUND_MIXER_WRITE_IGAIN 

int * // 1-0 

0XC0044D0D 


SOUND_MIXER_WRITE_OGAIN 

int * // 1-0 

0XC0044D0E 


SOUND_MIXER_WRITE_LINE1 

int * // 1-0 

0XC0044D0F 


S0UND_MIXER_WRITE_LINE2 

int * // 1-0 

0XC0044D10 


S0UND_MIXER_WRITE_LINE3 

int * // 1-0 

0XC0044D1C 


SOUND_MIXER_WRITE_MUTE 

int * // 1-0 

0XC0044D1D 


SOUND_MIXER_WRITE_ENHANCE 

int * // 1-0 

0XC0044D1E 


SOUND_MIXER_WRITE_LOUD 

int * // 1-0 

0XC0044DFF 


SOUND_MIXER_WRITE_RECSRC 

int * // 1-0 

i c 1 u d e /1 i n u x / u ms d o s f j 

i. h> 



0X000004D2 


UMSDOS_READDIR_DOS 

struct umsdos_ioctl * // 1-0 

0X000004D3 


UMSDOS_UNLINK_DOS 

const struct umsdos_ioctl * 

0X000004D4 


UMSDOS_RMDIR_DOS 

const struct unisdos_ioctl * 

0X000004D5 


UMSDOS_STAT_DOS 

struct umsdos_ioctl * // I-0 

0X000004D6 


UMSDOS_CREAT_EMD 

const struct unisdos_ioctl * 

0X000004D7 


UMSDOS_UNLINK_EMD 

const struct unisdos_ioctl * 

0X000004D8 


UMSDOS_READDIR_EMD 

struct umsdos_ioctl * // 1-0 

0X000004D9 


UMSDOS_GETVERSION 

struct umsdos_ioctl * 

0X000004DA 


UMSDOS_INIT_EMD 

void 

0X000004DB 


UMSDOS_DOS_SETUP 

const struct umsdos_ioctl * 

0X000004DC 


UMSDOS_RENAME_DOS 

const struct umsdos_ioctl * 

icl ude/1 i nux/vt. h> 

0x00005600 


VT_OPENQRY 

int * 

0x00005601 


VT_GETMODE 

struct vt_mode * 

0x00005602 


VT_SETMODE 

const struct vt_mode * 

0X00005603 


VT_GETSTATE 

struct vt_stat * 

0X00005604 


VT_SENDSIG 

void 

0X00005605 


VT_RELDISP 

int 

0x00005606 


VT_ACTIVATE 

int 

0x00005607 


VT_WAI TACTI VE 

int 

0X00005608 


VT_DISALLOCATE 

int 

0X00005609 


VT_RESIZE 

const struct vt_sizes * 

0X0000560A 


VT RESIZEX 

const struct vt consize * 



ioctl 



MORE ARGUMENTS 

Some ioctis take a pointer to a structure that contains additional pointers. These are documented herein alphabetical order. 
cdromreadaudio takes an input pointer const struct cdrom read audio *. T he but field points to an output buffer of length 

nframes * CD FRAMESIZE RAW. 


cdromreadcooked, cdromreadmodei , cdromreadmode 2 ( and cdrom-readraw take an input pointer const struct cdrom msf *.They 
use the same pointer as an output pointer to char []. The length varies by request. For cdromreadmodei, most drivers use 
cd_framesize, but the optics storage driver uses opt blocksize instead (both have the numerical value2048). 


CDROMREADCOOKED 

CDROMREADMODEI 

CDR0MREADM0DE2 

CDROMREADRAW 


char [CD_FRAMESIZE] 
char [CD_FRAMESIZE or OPT_BLOCKSIZE] 
char [CD_FRAMESIZE_RAW0] 
char [CD_FRAMESIZE_RAW] 


EQL_ENSLAVE, EQL_EMANCIPATE, EQL_GETSLAVECFG, EQL_SETSLAVECFG, EQL_GETMASTERCFG, and EQL_SETMASTERCFG take a Struct 

ifreq *.Theifr data field isa pointer to another structure as follows: 


EQL_ENSLAVE 

EQL_EMANCIPATE 

EQL_GETSLAVECFG 

EQL_SETSLAVECFG 

EQL_GETMASTERCFG 

EQL_SETMASTERCFG 


const struct slaving_request * 
const struct slaving_request * 
struct slave_config * // 1-0 
const struct slave_config * 
struct master_config * 
const struct master_config * 


fdrawcmd takes a struct floppy raw cmd *. If flags & fd raw write is nonzero, then data points to an i nput buffer of length 
length. If flags & FD RAW READ is nonzero, then data points to an output buffer of length length. 

GI0_F0NTX and PIO_FONTX take a struct console font desc * Or a const struct console_font_desc *, respectively, chardata 
points to a buffer of char [charcount]. This is an output buffer for gio_fontx and an input buffer for pio fontx. 

GIOJJNIMAP and PIOJJNIMAP take a struct unimapdesc * Or a const struct unimapdesc *, respectively, entries points to a 
buffer of struct unipair [entry ct]. T his is an output buffer for giojjnimap and an input buffer for piojjnimap. 

kdaddio, kddelio, kddisabio, and kdenabio enable or disable access to I/O ports They are essentially alternate i nterfaces to 

ioperra. 

kdmapdisp and kdunmapdisp enable or disable memory mappings or I/O port access. They are not implemented in the kernel. 

scsi_ioctl_probe_host takes an input pointer const int *, which isa length. It uses the same pointer as an output pointer to 
a char n buffer of this length. 

siocaddrt and siocdelrt take an input pointer whose type depends on the protocol: 

M OSt protocols const struct rtentry * 

AX.25 const struct ax25_route * 

NET/ROM const struct nr_route_struct * 


siocgifconf takes a struct ifconf *.Theifc but field points to a buffer of length ifc ien bytes, into which the kernel writes 
a list Of type struct ifreq []. 

siocsifhwaddr takes an input pointer whose type depends on the protocol: 

M OSt protocols const struct ifreq * 

AX.25 const char [AX25_ADDR_LEN] 

tioclinux takes a const char *. It usesthisto distinguish several independent subcases. In the following table n + too means 
foo after an N-byte pad. struct selection isimplicitly defined in drivers/char/selection.c: 
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TIOCLINUX-2 

TIOCLINUX-3 

TIOCLINUX-4 

TIOCLINUX-5 

TIOCLINUX-6 

TIOCLINUX-7 

TIOCLINUX-10 


1 + const struct selection * 

void 

void 

4 + const struct f long [8]; g * 
char * 
char * 

1 + const char * 


DUPLICATE ioctlS 

This list does not include ioctisin the range siocdevprivate and siocprotoprivate: 


0X00000001 

FDSETPRM 

0X00000002 

FDDEFPRM 

0X00005382 

CDROMAUDIOBUFSIZ 

0x00005402 

S N DCT L_TM R_S TART 

0X00005403 

SNDCTL_TMR_STOP 

0X00005404 

SNDCTL_TMR_CONTINUE 


FIBMAP 

FIGETBSZ 

SCSI_IOCTL_GET_IDLUN 

TCSETS 

TCSETSW 

TCSETSF 

Linux, 17 September 1995 


ioperm 

ioperm — Sets port input/output permissions 

SYNOPSIS 

#include <unistd.h> 

int ioperm(unsigned long from, unsigned long num,inttur non ); 

DESCRIPTION 

ioperm sets the port access permission bits for the process for n u m bytes starting from port address from to the value turn, on. 
The use of ioperm requires root privileges. 

Only the first 0x3ff I/O ports can be specified in this manner. For more ports, theiopi function must be used. Permissions 
are not inherited on fork, but on exec they are. This is useful forgiving port access permissions to nonprivileged tasks. 

RETURN VALUE 

O n success, 0 is returned. 0 n error, -1 is returned and errno isset appropriately. 

C0NF0RMST0 

ioperm is Linux specific. 

SEE ALSO 

iopl(2) 

Linux, 21 January 1993 


iopl 

iopi— Changes I/O privilege level 



ipc 



SYNOPSIS 

#include <unistd.h> 
int iopl(int level ); 

DESCRIPTION 

iopi changes the I/O privilege level of the current process, as specified in i evei. 

Thiscall isnecessary to allow 8514-compatible X servers to run under Linux. Because theseX servers require access to all 
65536 I/O ports, the ioperm call is not sufficient. 

In addition to granting unrestricted I/O port access, running at a higher I/O privilege level also allows the process to disable 
interrupts This will probably crash the system and is not recommended. 

T he I/O privilege level foranormal processisO. 

RETURN VALUE 

On success, 0 is returned. 0 n error, -1 is returned and errno is set appropriately. 

ERRORS 

einval level is greater than 3. 

eperm T he current user is not the superuser. 

NOTES FROM THEKERN EL SOURCE 

iopi has to be used when you want to access the I/O ports beyond the 0x3ff range T 0 get the full 65536 ports bitmapped, 
you'd need 8KB of bitmap^process, which isabit excessive. 

SEE ALSO 

ioperm(2) 

Linux0.99.11, 24July 1993 


ipc 

ipc— System V IPC system calls 

SYNOPSIS 

int ipc(unsigned int call, int first, int second, 
int third, void *ptr, long fifth); 

DESCRIPTION 

ipc isacommon kernel entry point for the System V IPC calls for messages, semaphores, and shared memory, cal 1 
determines which IPC function to invoke; the other arguments are passed through to the appropriate call. 

User programs should call the appropriate functions by their usual names. 0 nly standard library implementors and kernel 
hackers need to know about ipc. 

SEE ALSO 

msgctl(2), msgget(2), msgrcv(2), msgsnd(2), semctl(2), semget(2), semop(2), shmat(2), shmctl(2), shmdt(2), shmget(2) 

Linux 1.2.4,15 April 1995 
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kill 

kin— Sends signal to a process 

SYNOPSIS 

#include <sys/types.h> 

#include <signal.h> 

int kill(pid t pi d,intsi g); 

DESCRIPTION 

The kin system call can beused to send any signal to any process group or process. 

If pi d is positive, then signal si 9 is sent to pi d. In this case, 0 is returned on success and a negative value is returned on error. 

If pi d equals - 1 , then si g is sent to every process except the first one from higher numbers in the proc table to lower. In this 
case, 0 is returned on success, or the error condition resulting from signaling the last process is returned. 

If pi d is less than - 1 , then si g is sent to every process in the process group -pi d. In this case, the number of processes the 
signal was sent to is returned and a negative value is returned for failure. 

RETURN VALUE 

On success, 0 is returned. 0 n error, -1 is returned and errno is set appropriately. 

ERRORS 

einval An invalid signal issent. 

esrch Thepid or process group does not exist. N otethat an existing process might be a zombie a 

process that already committed termination, but has not yet been waitoed for. 
eperm The effective userlD of the process calling kiii() is not equal to the effective user ID of p i d, 

unless the superuser called kiii(). 

BUGS 

It is impossible to send a signal to task number one, themit process, for which it has not installed a signal handler. This is 
doneto ensure that the system isnot brought down accidentally. 

C0NF0RMST0 

SVID, AT&T, POSIX.1, X/OPEN, BSD 4.3 

SEE ALSO 

exit(2), exit(2), signal(2), signal(7) 

Linux, 1 N ovember 1995 


killpg 

kiiipg — Sends signal to a process group 

SYNOPSIS 

#include <signal.h> 

int killpg(int pgrp,intsi g); 

DESCRIPTION 

kiiipg sends the signal si 9 to the process group pgr p. Seesigaction(2) for a list of signals. If pgr p iso, kiiipg sends the signal 
to the sendi ng process's process group. 



link 



The sending process and members of the process group must have the same effective user ID, or the sender must be the 
superuser. Asa single special case, the continue signal sigcont may be sent to any process that is a descendant of the current 
process. 

RETURN VALUE 

On success, 0 is returned. 0 n error, -1 is returned and errno isset appropriately. 

ERRORS 

einval sig is not a valid signal number. 

esrch N 0 process can be found in the process group specified by pgr p. 

esrch T he process group was given as 0 , but the sending process does not have a process group. 

eperm The sendi ng process is not the superuser and one or more of the target processes has an 

effective user ID different from that of the sendi ng process. 

HISTORY 

Thekiiipg function call appeared in BSD4.0. 

SEE ALSO 

kill(2), getpgrp(2), signal(2) 

BSD Man Page 23July 1993 


link 

link— M akes a new name for a file 

SYNOPSIS 

#include <unistd.h> 

int link(const char *oI dpat h, const char *newpath); 


DESCRIPTION 

link creates a new link (also known as a hard link) to an existing file. 

If newpat h exists, it will not be overwritten. 

This new name may be used exactly as the old one for any operation; both names refer to the same file (and so have the same 
permissions and ownership) and it is impossible to tell which name was the original. 


RETURN VALUE 

O n success, 0 is returned. 0 n error, -1 is returned and errno isset appropriately. 


ERRORS 

EXDEV 
EPERM 
EFAULT 
EACCES 


ENAMETOOLONG 

ENOENT 

ENOTDIR 


01 d pat h and newpat h arenoton the same filesystem. 

Thefilesystem containing oi d pat h and newpat h does not support the creation of hard links. 
01 d pat h or newpat h points outside your accessible address space. 

Write accessto thedirectory contai ni ng newpat h isnot allowed for the process's effective 
UID, or one of the directories in o i d pat h or newpat h did notallow search (execute) 
permission. 

0 1 d p a t h Or newpat h wastOO long. 

A directory component in oi dpat h or newpat h does not exist or isa dangling symbolic link. 
A component used as a directory in oi dpat h or newpat h isnot, in fact, a directory. 
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enomem Insufficient kernel memory was available. 

erofs Thefileison a read-only filesystem. 

eexist newpat h already exists. 

emlink The file referred to by oi dpat h already has the maximum number of links to it. 

eloop oi d pat h or newpat h contains a reference to a circular symbolic link, that is, a symbolic link 

whose expansion contains a reference to itself. 

enospc The device containing the file has no room for the new directory entry. 

eperm oi dpat h isthe. or.. entry of a directory. 

NOTES 

H ard links, as created by link, cannot span filesystems. U sesymiink if this is required. 

C0NF0RMST0 

SVID, AT&T, POSIX, BSD 4.3 

BUGS 

On N FS file systems, the return code may be wrong in case the N FS server performs the I ink creation and dies before it can 
say so. Use stat(2) to find out if the I ink was created. 

SEE ALSO 

symlink(2), unlink(2), rename(2), open(2), stat(2), ln(l), link(8) 

Linux, 17 August 1994 


listen 

listen— Listens for connectionson a socket 

SYNOPSIS 

#include <sys/socket.h> 
int listen(int_s ,int backlog); 

DESCRIPTION 

T o accept connections, a socket is first created with socket(2), a willingness to accept incoming connections and a queue 
limit for incoming connections are specified with listen, and then the connections are accepted with accept(2). The listen 
cal I appl i es on ly to sockets of type sock_stream or sock_seqpacket. 

Thebacki og parameter defines the maximum length the queue of pending connections may grow to. If a connection request 
arrives with the queue full, the client might receive an errorwith an indication of econnrefused, or, if the underlying protocol 
supports retransmission, the request may be ignored so that retries may succeed. 

RETURN VALUE 

On success, 0 is returned. 0 n error, -1 is returned and errno is set appropriately. 

ERRORS 

EBADF 
ENOTSOCK 
EOPNOTSUPP 

HISTORY 

The listen function call appeared in BSD 4.2. 


The arguments is not a valid descriptor. 

The arguments is not a socket. 

T he socket is not of a type that supports the operation listen. 
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/seek 

BUGS 

If the socket is of type af_inet and the backlog argument is greater than 128, it is silently truncated to 128. For portable 
applications, don't rely on this valuesince BSD (and at least some BSD -derived systems) limit the backlog to 5. 

SEE ALSO 

accept(2), connect(2), socket(2) 

BSD Man Page 23July 1993 

llseek 

_iiseek— Repositionsthe read/write file offset 

SYNOPSIS 

#include <unistd.h> 

#include <linux/unistd.h> 

_syscall5(int, llseek, uint, fd, ulong, hi, ulong, lo, loff_t*,res,uint,wh); 

int llseek(unsigned int fd, unsigned long offsethi gh , 

unsigned long offsetl ow, loff_t * result , unsigned int whence); 

DESCRIPTION 

The_iiseek function repositions the offset of thefile descriptor f d to ( off $et_hi gh«32) | of tset_iow bytes relative to the 
beginning of thefile the current position in thefile, or the end of thefile, depending on whether whence is seek_set, 
SEEK_cuR,orsEEK_END, respectively. It returns the resulting fi le position in theargumentresui t . 

RETURN VALUES 

Upon successful completion, _iiseek returns®. Otherwise, a value of-i is returned and emno is set to indicate the error. 

ERRORS 

ebadf fd is not an open file descriptor. 

EINVAL whence isinvalid. 

C0NF0RMST0 

T his function is Linux specific. 

BUGS 

There is no support for files with a size of 2GB or more. 

SEE ALSO 

lseek(2) 

Linux 1,2.9,10 Junel995 

lseek 

lseek— Repositions read/write file offset 

SYNOPSIS 

#include <unistd.h> 

off_t lseek(int f i I des ,off_t offset ,int whence) ; 
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DESCRIPTION 

T he lseek function repositions the offset of thefile descriptor f i ides to the argument of f set according to the directive 
whence. The argument fi i des must bean open file descriptor, lseek repositionsthefile pointer f i ides as follows: 

If whence issEEK_sET, the offset is set to offset bytes. 

If whence issEEK_cuR, the offset is set to its current location plus of f set bytes. 

If whence issEEK_END, the offset i s set to the size of the fi le plus of f s e t bytes. 

The lseek function allows the file offset to beset beyond the end of the existing end-of-file of the file If data is later written 
at this point, subsequent reads of the data in the gap return bytes of zeros (until data is actually written into the gap). 

Some devices are incapable of seeking. The value of the pointer associated with such a device is undefined. 

RETURN VALUES 

Upon successful completion, lseek returns the resulting offset location as measured in bytes from the beginning of thefile. 
Otherwise, a value of -i is returned and emno is set to indicate the error. 

ERRORS 

ebadf tildes is not an open file descriptor. 

espipe f i i des isassociated with a pipe, socket, or FIFO. 

einval whence is not a proper value. 

C0NF0RMST0 

POSIX, BSD 4.3 

BUGS 

This document's use of whence is incorrect English, but maintained for historical reasons. 

SEE ALSO 

dup(2), open(2), fseek(3) 

Linux 1.2.9,10 ]unel995 

mkdir 

mkdir— C reates a di rectory 

SYNOPSIS 

#include <sys/types.h> 

#include <fcntl.h> 

#include <unistd.h> 

int mkdir(const char *pat hname, mode_t mode); 

DESCRIPTION 

mkdir attempts to create a di rectory named pathname. 

mode specifies the permissions to use. Itis modified by the process's umask in the usual way: the permissions of the created 
fi le is (mode & 'umask). 

The newly created directory will be owned by the effective U ID of theprocess. Ifthedi rectory containing the file has the set 
group ID bit set, or if the filesystem is mounted with BSD group semantics, the new directory will inherit the group 
ownership from its parent; otherwise, it will be owned by the effective GID of the process. 

If the parent directory has the set group ID bit set, so will the newly created directory. 




mknod 


795 


RETURN VALUE 

mkdir returnso on success, or -i if an error occurred (in which case, errno is set appropriately). 

ERRORS 

EEXIST 
EFAULT 
EACCES 

ENAMETOOLONG 
ENOENT 
ENOTDIR 
ENOMEM 
EROFS 
ELOOP 

ENOSPC 
ENOSPC 

BUGS 

In some older versions of Linux (for example, 0.99pl7) all the normal filesystems sometime allow thecreation of two filesin 
the same directory with the same name. This occurs only rarely and only on a heavily loaded system. It is believed that this 
bug was fixed in the M i nix filesystem in Linux 0.99pl8 prerelease; and it is hoped that it was fixed in the other filesystems 
shortly afterward. 

There are many infelicities in theprotocol underlying N FS. 

SEE ALSO 

read(2), write(2), fcntl(2), close(2), unlink(2), open(2), mknod(2), stat(2), umask(2), mount(2), socket(2), sacket(2), fopen(3) 

Linux 1.0, 29 March 1994 

mknod 

mknod— C reates a di rectory 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/stat.h> 

#include <fcntl.h> 

#include <unistd.h> 

int mknod(const char *pat hname , mode_t mode,dev_t dev); 

DESCRIPTION 

mknod attempts to create a filesystem node (file, device special file, or named pipe) named pathname, specified by mode and dev. 
mode specifies both the permissions to use and the type of node to be created. 

It should be a combination (using bitwise or) of one of the file types listed below and thepermissionsforthenew node. 

The permissions are modified by the process's umask in the usual way: The permissions of the created node is (mode & 

’umask). 


pathname already exists (not necessarily as a directory), 
p a t h n a me poi nts outsi de your accessi bl e address space. 

The parent di rectory does not allow write permission to the process, or one of the 
directories in pathname did not allow search (execute) permission, 
pathname wastOO long. 

A directory component in pat hname does not exist or isa dangling symbolic link. 

A component used as a directory in pathname is not, in fact, a directory. 
Insufficientkernelmemorywasavailable. 

pathname refers to a file on a read-only filesystem and write access was requested, 
pathname contains a reference to a circular symbolic link, that is, a symbolic link whose 
expansion contains a reference to itself. 

The device containing pathname has no room for the new directory. 

Thenew directory cannot be created because the user's disk quota isexhausted. 
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The file type should be one of s_ifreg, s_ifchr, s_ifblk, or s_ififo to specify a normal file (which will be created empty), 
character special file, block special file, or FIFO (named pipe), respectively, or 0, which will create a normal file. 

If thefiletypeiss_iFCHR or s_ifblk, then dev specifies the major and minor numbers of the newly created device special file; 
otherwise, it is ignored. 

The newly created nodewill be owned by the effective UID of theprocess. If the directory containing the node has the set 
group ID bit set, or if the filesystem is mounted with BSD group semantics, thenew node will inherit the group ownership 
from its parent directory; otherwise it will be owned by theeffectiveGID of theprocess. 

RETURN VALUE 

mknod returns 0 on success, or -1 if an error occurred (in which case, errno is set appropriately). 

ERRORS 

EPERM 

EINVAL 
EEXIST 
EFAULT 
EACCES 

ENAMETOOLONG 
ENOENT 
ENOTDIR 
ENOMEM 
EROFS 
ELOOP 

ENOSPC 

BUGS 

In some older versions of Linux (for example, 0.99pl7) all the normal filesystems sometime allow thecreation of two filesin 
the same directory with the same name. This occurs only rarely and only on a heavily loaded system. It is believed that this 
bug was fixed in the M i nix filesystem in Linux 0.99pl8 prerelease; and it is hoped that it was fixed in the other filesystems 
shortly afterward. 

mknod cannot be used to create directories or socket files, and cannot be used to create normal files by users other than the 
superuser. 

There are many infelicities in theprotocol underlying N FS. 

SEE ALSO 

read(2), write(2), fcntl(2), close(2), unlink(2), open(2), mkdir(2), stat(2), umask(2), mount(2), socket(2), fopen(3) 

Linux 1.0, 29 March 1994 


mode requested creation of something other than a FIFO (named pipe), and thecaller is not 
thesuperuser; also returned if the filesystem containing pat hname does not support the type 
of node requested. 

mode requested creation of something other than a normal file, device special file or FIFO. 
pathname already exists. 

p a t h n a me poi nts outsi de your accessi bl e address space. 

The parent di rectory does not allow write permission to theprocess, or one of the 
directories in pathname did not allow search (execute) permission, 
pat hname wastOO long. 

A directory component in pat hname does not exist or isa dangling symbolic link. 

A component used as a directory in pathname is not, in fact, a directory. 
Insufficientkernelmemorywasavailable. 

pathname refers to a file on a read-only filesystem and write access was requested, 
pathname contains a reference to a circular symbolic link, that is, a symbolic link whose 
expansion contains a reference to itself. 

T he devicecontai ning pa t h n a me has no room forthenew node. 


mlock 

miock — D isables pagi ng for some parts of memory 
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SYNOPSIS 

#include <sys/mman.h> 

int mlock(const void *addr , size_t len); 

DESCRIPTION 

miock disables paging for the memory in the range starting at ad dr with length i e n bytes. All pages that contain a part of the 
specified memory range are guaranteed to be resident in RAM when themiock system call returns successfully and they are 
guaranteed to stay in RAM until the pages are unlocked again by muniock or muniockaii or until the process terminates or 
starts another program with exec. Child processes do not inherit page locks across a fork. 

M emory locking has two main applications: real-time algorithmsand high-security data processing. Real-timeapplications 
require deterministic timing, and, like scheduling, paging is one major cause of unexpected program execution delays. Real¬ 
time applicationswill usually also switch to a real-time scheduler with sched setscheduier. 

C ryptographic security software often handles critical bytes such as passwords or secret keys as data structures. As a result of 
paging, these secrets could be transferred onto a persistent swap store medium, where they might be accessible to the enemy 
long after the security software has erased the secrets in RAM and terminated. 

M emory locks do not stack, that is, pages that have been locked several times by cal Is to miock or miockaii will be unlocked 
by a single call to muniock for the corresponding range or by muniockaii. Pages that are mapped to several locations or by 
several processes stay locked into RAM as long as they are locked at least at one location or by at least one process. 

On POSIX systems on which miock and muniock are available _posix_memlock_range is defined in <unistd.h> and the value 
pagesize from <iimits.h> indicates the number of bytes per page. 

RETURN VALUE 

On success, miock returns 0 . 0 n error, -i is returned, errno is set appropriately, and no changes are made to any locks in the 
address space of the process. 

ERRORS 

ENOMEM 

EPERM 

EINVAL 

STANDARDS 

POSIX.lb, SVR4 

SEE ALSO 

munlock(2), mlockall(2), munlockall(2). 

Linux 1.3.43, 26 November 1995 

mlockall 

miockaii— D isables pagi ng for cal li ng process 

SYNOPSIS 


Some of the specified address range does not correspond to mapped pages in the address 
space of the process or the process tried to exceed the maxi mum number of allowed locked 
pages. 

The calling process does not have appropriate privileges. Only root processes are allowed to 
lock pages. 

len was not a positive number. 


#include <sys/mman.h> 
int mlockall(int flags); 
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DESCRIPTION 

miockaii disables paging for all pages mapped into the address space of the calling process. Thisincludesthepages of the 
code, data and stack segments, shared libraries, user space kernel data, shared memory, and memory-mapped files. All 
mapped pages are guaranteed to be resident in RAM when themiockaii system call returns successfully and they are 
guaranteed to stay in RAM until the pages are unlocked again by muniock or muniockaii or until the process terminates or 
starts another program with exec. C hild processes do not inherit page locks across a fork. 

M emory locking has two main applications: real-time algorithms and high-security data processing. Real-timeapplications 
require deterministic timing, and, like scheduling, paging is one major cause of unexpected program execution delays. Real¬ 
time applications will usually also switch to a real-time scheduler with sched setscheduier. Cryptographic security software 
often handles critical bytes such as passwords or secret keys as data structures. Asa result of paging, these secrets could be 
transferred onto a persistent swap store medium, where they might be accessible to the enemy long after the security software 
has erased the secrets in RAM and terminated. For security applications, only small parts of memory have to be locked, for 
which miock is available. 

Then ags parameter can be constructed from the logical or of the following constants: 

mcl_current Lock all pages that are currently mapped into the address space of the process. 

mcl_future Lock all pagesthatwill becomemapped into the address space of the process in thefuture. 

These could be, for instance, new pages required by a growing heap and stack as well as new 
memory mapped fi les or shared memory regions. 

If mcl_future has been specified and the number of locked pages exceeds the upper limit of allowed locked pages, the system 
call that caused the new mapping will fail with enomem. If these new pages have been mapped by the growing stack, the kernel 
will deny stack expansion and and asiGSEGv. 

Real-time processes should reserve enough locked stack pages before entering thetime-critical section, so no page fault can be 
caused by function calls This can be achieved by calling a function that has a sufficiently large automatic variableand that 
writes to the memory occupied by this large array in order to touch these stack pages. This way, enough pages will be 
mapped for the stack and can be locked into RAM . The dummy writes ensure that not even copy-on-write page faults can 
occur in the critical section. 

M emory locks do not stack, that is pages that have been locked several times by cal Is to miockaii or miock will be unlocked 
by a single call to muniockaii. Pages that are mapped to several locations or by several processes stay locked into RAM as long 
as they are locked at least at one location or by at least one process. 

On POSIX systemson which miockaii and muniockaii are available, posix memlock isdefined in <unistd.h>. 

RETURN VALUE 

On success, miockaii returns 0 . On error, -i is returned and errno is set appropriately. 

ERRORS 

ENOMEM 
EPERM 

EINVAL 

STANDARDS 

POSIX.lb, SVR4 

SEE ALSO 

munlockall(2), mlock(2), munlock(2) 


The process tried to exceed the maximum number of allowed locked pages. 

T he call i ng process does not have appropri ate privi leges. Only root processes are al lowed to 
lock pages. 

U nknown flags were specified. 


Linux 1.3.43, 26 November 1995 
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mmap, munmap 

mmap, munmap— M ap or unmap files or devices into memory 

SYNOPSIS 

#include <unistd.h> 

#include <sys/mman.h> 

#ifdef POSIX MAPPED FILES 

void * mmap(void *s t a r t , size_t I engt h ,int pr ot ,int flags ,int f d ,off_t offset ); 
int munmap (void *start, size_t length); 

#endif 


DESCRIPTION 

The mmap function asks to map i engt h bytes starting at offset offset from thefile (or other object) specified by f d into 
memory, preferably at address start . This latter address is a hint only, and is usually specified as 0 . The actual place where 
the object is mapped is returned by mmap.Theprot argument describes the desired memory protection. It has the following 
bits: 

prot exec Pages may be executed. 

prot read Pages may be read. 

prot_write Pages may be written. 

T hef 1 ags parameter specifies the type of the mapped object, mapping options, and whether modifications made to the 
mapped copy of the page are private to the process or are to be shared with other references. It has the following bits: 

map_fixed Do not select a different address than the one specified. If the specified address cannot be 

used, mmap will fail. If map_fixed is specified, start must be a multiple of the pagesize. Use of 
this option is discouraged. 

map_shared Sharethis mapping with all other processesthat map this object. 

map private C reate a private copy-on-write mapping. 

These three flags are described in POSIX.4. Linux also knows about map denywrite, map_executable, and mapanon(ymous). 

The munmap system call deletes the mappings for the specified address range and causes further references to addresses within 
the range to generate invalid memory references. 

RETURN VALUE 

On success, mmap returns a pointer to the mapped area. On error, map_failed (- 1 ) is returned and errno is set appropriately. 
On success, munmap returns 0 , and on failure it returns-i and sets errno (probably to einval). 


ERRORS 

EBADF 

EACCES 

EINVAL 

ETXTBUSY 

EAGAIN 

ENOMEM 


f d is not a valid file descriptor (and map_anonymous was not set). 

map_private was asked, but f d is not open for reading. 0 r map^shared was asked and 

protjiirite is set, fd isnotopen for writing. 

start or i engt h, and of f set aretoo large, or not aligned on a pagesize boundary. 
mapdenywrite was set but theobject specified by f d isopen forwriting. 

Thefile has been locked, or too much memory has been locked. 

N o memory is available. 


C0NF0RMST0 

POSIX.4. 
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SEE ALSO 

getpagesize(2), msync(2), shm_open(2), B. 0. Gallmeister, P05IX.4, O'Reilly, pp. 128-129, 389-391. 

Linux 1.3.86,12 April 1996 

modify_ldt 

modif y_ldt— G etS Or sets ldt 

SYNOPSIS 

#include <linux/ldt.h> #include <linux/unistd.h> 

_syscall3( int, modify_ldt, int, func, void *, ptr, unsigned long, bytecount ) 
int modify_ldt(int func, void *ptr, unsigned long bytecount); 

DESCRIPTION 

modif y_idt reads or writes the local descriptor table (ldt) for a process. T he idt is a per-process memory-management table 
used by the i386 processor. For more information on thistable, see an Intel 386 processor handbook. 

When func is 0 , modif y_idt reads the ldt into the memory pointed to by ptr . The number of bytes read is the smaller of 
bytecount and the actual size of theidt. 

When func is i, modif y_idt modifies one ldt entry, ptr points to a modi f y.lbt j dt_s structure and bytecount must equal the 
size of this structure. 

RETURN VALUE 

On success, modify_idt returns either the actual number of bytes read (for reading) or 0 (for writing). On failure, modify_idt 
returns -1 and setsermo. 

ERRORS 

enosys func is neither 0 nor 1 . 

einval ptr iso, orfunc is i and bytecount is not equal to the size of the structure 

modifyj d t _ i d t _ s ,or func is i and the new idt entry hasillegal values. 
efault ptr points outside the address space. 

SEE ALSO 

vm86(2) 

Linux 1.3.6, 22July 1995 

get_kernel_syms,createjnodule, init jiodule, deletejnodule 

get_kernel_syms, createjnodule, init_module, deletejnodule —Loadable module Support 

SYNOPSIS 

#include <linux/module.h> 

int get_kernel_syms(struct kernel_sym *table); 

int createjnodule(char *module_name, unsigned long size); 
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int init_module(char *module_name, char *code, unsigned codesize, 
struct mod_routines *routines, struct symbol_table *symtab); 

int delete_module(char *module_name); 

struct kernel_sym { 

unsigned long value; 
char name[SYM_MAX_NAME]; 


struct mod_routines { 
int (*init)(void); 
void (*cleanup)(void); 

}; 


struct module_ref { 

struct module *module; 
struct module_ref *next; 

}; 


struct internal_symbol { 
void *addr; 
char *name; 

}; 


struct symbol_table { 

int size; /* total, including string table!!! */ 
int n_symbols; 
int n_refs; 

struct internal_symbol symbol[0]; 
struct module_ref ref[0]; 

}; 

DESCRIPTION 

These system calls have not yet been included in any library, which means that they have to be called by the 
syscaii(_NR_f unction) mechanism. get_kernei_syms( table); hastwo uses: First, if table is null, this call will only return the 
number of symbols, including module names, that are available This number should be used to reserve memory for that 
many items of struct kernel sym. 

If table is not null, this call will copy all kernel symbols and module names (and version info) from the kernel to the space 
pointed to by table. The entries are ordered in module LIFO order. For each module an entry that describes the module will 
be followed by entries describing thesymbols exported by this module. 

N otethat for symbols that describe a module, the value part of the structure will contain the kernel address of the structure 
that describes the module 

The name part of the structure is the module name prepended with #, as in #my module. The symbol that describes a module 
will appear before the symbols defined by thismodule 

Ahead of the kernel resident symbols, a module name symbol with the "dummy'' name# will appear. This information can 
beused to build atableof module references when modules are stacked (or layered). create_moduie(moduie_name, size); will 
allocate size bytes of kernel space for a module and also create the necessary kernel structures— called name— for the new 
module. The module wi II now exist in kernel space, with the status mod uninitialized, init moduie(moduie_name, code, 
codesize, routines, symtab);. 

This is the actual "module loader" that will load the module named name into the kernel. The parameters code and codesize 
refer to the relocated binary object module that is codesize bytes long. N otethat the first 4 bytes will beused as a reference 
counter in kernel space, updated by the mod_inc_use_count and mod_dec_use_count macros. 
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The functions described in routines will be used to start and stop the module. These pointers should therefore contain the 
addresses of the init_moduie() and cieanup_moduie() functions that have to be defined for all loadable modules. 

If a module wants to export symbols for use by other modules, or if the module makes references to symbols defined by other 
modules, the parameter symtab has to point to a structure that describes these. A null value for symtab means that no symbols 
are exported and no references to other modules are made. 

The symtab that will be copied into the kernel consists of a symbol table structure immediately followed by a string table, 
containing the names of the symbols defined by the module. The size element has to include the size of this string table as 
well. Special considerations follow. 

T he n_symbois and n_refs elements tells how manysymbolsand how many module references are included in the symbol 
table structure. Immediately after these integers, the array of symbol definitions follows. The name element in each struct 
internal symbol should actually not bean ordinary pointer, but instead the offset of the corresponding string table entry 
relative to the start of the symbol table structure. 

When all defined symbols have been listed, thesymboi_tabie structure continues with thearray of module references, as 
described bythestruct moduie_ref elements Only the module field of these structures have to be initialized. The module 
addresses that were obtained from a previous get_kernei_syms call, for elements with names starting with # should be copied 
to thisfield. 

If the module could be successfully loaded, and if the call to the module function init module o also succeeds, the status of 
the module will be changed to mod_running. Otherwise, the kernel memory occupied by module will be freed. 

deiete_moduie(moduie_name) ; should beused to unload a module. If the module reference count shows that the module is not 
active, and if there are no references to this module from other modules, the module function cieanup_moduie() will be 
called. If all these steps succeed, the kernel memory occupied by the module and its structures will be freed. 

DIAGNOSTICS 

If there are any errors, these functions will return the value - 1 , and the global variable errno will contain the error number. A 
descriptive text will also be written on the console device. 

SEE ALSO 

insmod(l), rmmod(l), lsmod(l), ksyms(l) 

HISTORY 

T he module support was first conceived by Anonymous. 

Linux version by Bas Laarhoven (bas@vimec.m), 0.99.14 version byjon T ombs(jon@gtex 02 .us.es), extended by Bjorn 
Ekwall (bj0rn@blox.se). 

BUGS 

N aah... 

Linux, 25January 1995 


mount,umount 

mount, umount— M ount and unmount filesystems. 

SYNOPSIS 

#include <sys/mount.h> 

#include <linux/fs.h> 

int mount(const char *speci al f i I e, const char * dir , 

const char * fi I esystemtype, unsigned long rwflag , const void * data); 

int umount(const char *speci alfiI e); 

int umount(const char *dir); 
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DESCRIPTION 

mount attaches the filesystem specified byspeci ai fi i e (which is often a device name) to the directory specified by d i r. 
umount removes the attachment of the filesystem specified byspeci ai fi i e or d i r . 

Only the superuser may mount and unmount filesystems. 

Thefi I esystemtype argument may take one Of the values listed in /proc/f ilesystems (such as minix, ext 2 , msdos, proc, nfs, 
iso9660). 

T her wf i ag argument has the magic number bxcoed in the top 16 bits, and various mount flags (as defined in <iinux/fs.h>) in 
the low order 16 bits: 

#define MS_RDONLY 1 /* mount read-only */ 

#define MS_N0SUID 2 /* ignore suid and sgid bits */ 

#define MS_NODEV 4 /* disallow access to device special files */ 

#define MS_N0EXEC 8 /* disallow program execution */ 

#define MS_SYNC 16 /* writes are synced at once */ 

#define MS_REMOUNT 32 /* alter flags of a mounted FS */ 

#define MS_MGC_VAL 0XC0ED0000 

If the magic number is absent, then the last two arguments are not used. 

Thedata argument is interpreted by thedifferent filesystems. 


RETURN VALUE 

0 n success, 0 is returned. 0 n error, -1 is returned and errno isset appropriately. 


ERRORS 


The following error values result from filesystem type independent errors. Each filesystem type may have its own special 
errors and its own special behavior. See the kernel source codefor details. 


EPERM 

ENODEV 

ENOTBLK 

EBUSY 


EINVAL 


EFAULT 

ENOMEM 

ENAMETOOLONG 

ENOENT 

ENOTDIR 

EACCES 


ENXIO 

EMFILE 


The user is not the superuser. 

fi 1 esystemtype not configured in the kernel. 

speci a 1 f i 1 e isnot a block device (if a device was required). 

speci a 1 f i 1 e is already mounted. Or it cannot be remounted read-only because it still holds 
files open for writing. 0 r, it cannot be mounted on d i r because di r is still busy (it is the 
working directory of sometask, the mount point of another device, has open files, and so 
on). 

speci a 1 f i 1 e had an invalid superblock. Or, a remount was attempted, while speci a 1 f i 1 e 
was not already mounted on di r. 0 r, an umount was attempted, while di r was not a mount 
point. 

0 ne of the pointer arguments points outside the user address space. 

The kernel could not allocate a free page to copy filenames or data into. 

A pathname was longer than maxpathlen. 

A pathnamewasemptyorhad a nonexistent component. 

The second argument, or a prefix of the first argument, is not a directory. 

A component of a path was not searchable. 

0 r, mounting a read-only filesystem was attempted without giving theMs_RDONLY flag. 

Or, the block devices pec i ai f i 1 e is located on a filesystem mounted with the ms_nodev 
option. 

The major number of the block devices pec i ai f i 1 e is out of range. 

(In case no block device is required:) T able of dummy devices is full. 
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CONFORMSTO 

T hese functions are rather Linux specific. 

SEE ALSO 

mount(8), umount(8) 

Linux 1.1.67, 28 November 1994 

mprotect 

mprotect— Controls allowable accesses to a region of memory 

SYNOPSIS 

#include <sys/mman.h> 

int mprotect(caddr_t addr, size_t *len, int prot); 

DESCRIPTION 

mprotect controls how a section of memory can be accessed. If an access is disallowed by the protection given it, the program 
receives a sigsegv. 

prot is a bitwise-0 R of the following values: 
prot none T he memory cannot be accessed at all. 

prot_read T he memory can be read. 

prot_write T he memory can bewritten to. 

prot_exec Thememorycan contain executing code. 

The new protection replaces any existing protection. For example, if the memory had previously been marked prot_read, and 
mprotect is then called with prot prot_write, it will no longer be readable. 

RETURN VALUE 

On success, mprotect returns 0 . On error, -i is returned and errno is set appropriately. 

ERRORS 

einval addr isnot a valid pointer. 

efault The memory cannot be accessed. 

eacces The memory cannot be given the specified access. This can happen, for example if you 

mmap(2) afileto which you have read-only access, then ask mprotect to mark it prot_write. 
enomem Internal kernel structures could not be allocated. 

EXAMPLE 

#include <stdio.h> 

#include <stdlib.h> 

#include <errno.h> 

#include <sys/mman.h> 

int 

main(void) 

{ 



char *p; 
char c; 
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/* Allocate a buffer; it will have the default 
protection of PROT_READ]PROT_WRITE. */ 
p = malloc(1024); 

if (!p) { 

perror("Couldn 1 t malloc(1024)"); 
exit(errno); 


c = p[666]; /* Read; ok */ 

p[666] = 42; /* Write; ok */ 

/* Mark the buffer read-only. */ 
if (mprotect(p, 1024, PROT_READ)) { 
perrorf'Couldn't mprotect"); 
exit(errno); 


c = p[666]; /* Read; ok */ 

p[666] = 42; /* Write; program dies on SIGSEGV */ 

exit(0); 


SEE ALSO 

mmap(2) 


Linux 1.2, 23 Junel995 


mremap 

mremap— Remaps a virtual memory address 

SYNOPSIS 

#include <unistd.h> 

#include <sys/mman.h> 

void * mremap(void * ol d address , size_t oI d _ size , size_t new_size, unsigned long flags) 

DESCRIPTION 

mremap expands (or shrinks) an existing memory mapping, potentially moving it at the same time (controlled by thef lags 
argument and the avai I able vi rtual address space). 

oi d_ address is the old address of the virtual memory block that you want to expand (or shrink). N otethatoi d_ address has to 
be page aligned, oi d_si ze is the old size of the virtual memory block. new_s i ze is the requested size of the virtual memory 
block after the resize. 

Then ags argument is a bitmap of flags. 

In Linux the memory is divided into pages. A user process has oneorlinear virtual memory segments. Each virtual memory 
segment has one or more mappings to real memory pages (in the page table). Each virtual memory segment has its own 
protection (access rights), which may cause a segmentation violation if the memory is accessed incorrectly (for example, 
writing to a read-only segment). Accessing virtual memory outside of the segments will also cause a segmentation violation. 

mremap uses the Linux page table scheme, mremap changes the mapping between virtual addresses and memory pages. This can 
beused to implement a very efficient reaiioc. 
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FLAGS 

mremap_maymove I ndicates whether the operation should fail, or changes the virtual address if the resize 

cannot be done at the current virtual address. 

RETURN VALUE 

On success, mremap returns a pointer to the new virtual memory area. On error, -i is returned, and errno is set appropriately. 

ERRORS 

EINVAL 
EFAULT 


EAGAIN 
ENOMEM 

SEE ALSO 

getpagesize(2), reaiioc(3), maiioc(3), brk(2), sbrk(2), mmap(2), your favorite 0 S text book for more information on paged 
memory. (M odern Operating Systems byAndrew S. T annenbaum, Inside Linux by Randolf Bentson, TheDesgn oftheUNIX 
Operating System by M auricej. Bach.) 

Linux 1.3.87,12 April 1996 


An invalid argument was given. M ost likely oi d_addr ess was not page aligned. 

Segmentation fault. Some address in therangeoi d_address tooid_address+oid_size is an 
invalid virtual memory address for this process. You can also get efault even if there exist 
mappi ngs that cover the whole address space requested, but those mappings are of different 
types. 

The memory segment is locked and cannot be remapped. 

T he memory area cannot be expanded at the current vi rtual address, and the mre map_maymove 
flag is not set in flags. Or there is not enough (virtual) memory available. 


msgctl 

msgcti— H andles message control operations 

SYNOPSIS 

# include <sys/types.h> 

# include <sys/ipc.h> 

# include <sys/msg.h> 

int msgctl ( int ms q i d , int cmd , struct msqid_ds * buf ); 

int cmd, struct msqid_ds *buf; 

DESCRIPTION 

Thefunction performs the control operation specified by c md on the message queue with identifier ms q i d. Legal values for cmd 

are 

ipc_stat Copies info from the message queue data structure into the structure pointed to by but . The 

user must have read access privileges on the message queue. 

ipc_set Writes the values of some members of themsqid ds structure pointed to by buf to the 

message queue data structure, updating also itsmsg_ctime member. Considered members 
from the user-supplied struct msqid ds pointed to by buf aremsg_perm.uid, msg_perm.gid, 
and msg_perm.mode /* only lowest 9-bits */ msg_qbytes. 

T he calling process effective user ID must be one among superuser, creator or owner of the 
message queue. Only the superuser can raise the msgjbytes value beyond the system 
parameter msgmnb. 

ipc_rmid Remove immediately the message queue and its data structures awakening all waiting reader 

and writer processes (with an error return and errno set to eidrm). T he calling process 
effective user ID must be one among superuser, creator or owner of the message queue. 
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RETURN VALUE 

If successful, the return value will be otherwise, the return value will be -i with errno indicating the error. 

ERRORS 

For afailing return, errno will be set to one of the following values: 

eaccess The argument cmd isequal to ipc_stat, but the calling process has no read access permis¬ 

sions on the message queue ms q i d . 

efault The argument cmd hasvalueiPc_SET or ipc_stat, but the address pointed to by buf isn't 

accessible 

eidrm The message queue was removed. 

einval Invalid valueforcmd or ms q i d. 

eperm The argument cmd hasvalueiPc_SEToriPcjiMiD, but the calling process effective user ID 

has insufficient privileges to execute the command. N ote that this is also the case of a 
nonsuperuser process trying to increase the msg_qbytes value beyond the value specified by 
the system parameter msgmnb. 

NOTES 

TheiPcjNFo, msg_stat, and msg_info control callsareused by the ipcs(l) program to provide information on allocated 
resources. In the future these can be modified as needed or moved to a proc file system interface. 

SEE ALSO 

ipc(5), msgget(2), msgsnd(2), msgrcv(2) 

Linux 0.99.13,1 N ovember 1993 

msgget 

msgget— Gets a message queue identifier 

SYNOPSIS 

# include <sys/types.h> 

# include <sys/ipc.h> 

# include <sys/msg.h> 

int msgget ( key_t key, int msgflg ); 

DESCRIPTION 

The function returns the message queue identifier associated to the value of the key argument. A new message queue is 
created if key has value ipc_private or key isn't ipc_private, no existing message queue is associated to key , and ipc_creat is 
asserted in ms gf i g (that is, ms gf i g &ipc_creat isn't 0 ). The presence in ms gf 1 g of the fields ipc_creat and ipc_excl plays the 
same role with respect to the existence of the message queue, as the presence of o_creat and o_excl in the mode argument of 
the op_en(2) system call: That is, themsgget function fails if ms gf 1 g asserts both ipc_creat and ipc_excl and a message queue 
already exists for key. 

Upon creation, the lower 9 bits of the argument ms gf 1 g defi ne the access permissions (for owner, group, and others) to the 
message queue in the same format, and with the same meaning, as for the access permissions parameter in theopen(2) or 
creat(2) system calls (though the execute permissions are not used by the system). 

Furthermore, while creating, the system call initializes the system message queue data structure msqid ds as follows: 
msg_perm.cuid and msg_perm.uid are set to the effective user ID of the calling process. 
msg_perm.cgid and msg_perm.gid are set to the effective group ID of the calling process. 
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Thelowest-order 9 bits of msg_perm.mode are set to the lowest-order 9 bit of ms gf i g. 
msg_qnum, msg_lspid, msg_lrpid, msg_stime, and msg_rtime are Set to 0. 
msg_ctime issetto the current time 
msg_qbytes is set to the system limit MSGMNB. 

If the message queue already exists, the access permissions are verified, and a check is made to see whether it is marked for 
destruction. 

RETURN VALUE 

If successful, the return value will bethe message queue identifier (a positive integer), otherwise-i with errno indicating the 
error. 

ERRORS 

Forafailing return, errno will be set to one of the following values: 

eacces A message queue exists for key , but the calli ng process has no access permissions to the 

queue. 

eexist A message queue exists for key and ms gf i g was asserting both ipc_creat and ipc_excl. 

eidrm Themessagequeueismarked asto beremoved. 

enoent No message queue exists for key and msgfig wasn't asserting ipc_creat. 

enomem A message queue has to be created but the system has not enough memory for the new data 

structure. 

enospc A message queue has to be created but the system limit for the maximum number of 

message queues (msgmni) would be exceeded. 

NOTES 

ipc_private isn't a flag field, but a key_t type. If this special value is used for key, the system call ignores everything but the 
lowest-order 9 bits of ms gf i g and creates a new message queue (on success). 

T he following isasystem limit on message queue resources affecting a msgget call: 

msgmni Systemwide maximum number of message queues; policy dependent. 

BUGS 

Use of ipcprivate doesn't inhibit other processes the access to the allocated message queue. 

Asforthefiles, there is currently no intrinsic way for a process to ensure exclusive access to a message queue. Asserting both 
ipc_creat and ipc_excl in ms gf i g only ensures (on success) that a new message queue will be created; it doesn't imply 
exclusive access to the message queue. 

SEE ALSO 

ftok(3), ipc(5), msgctl(2), msgsnd(2), msgrcv(2) 

Linux 0.99.13,1 N ovember 1993 


msgop 

msgop— C ompletes message operations 


SYNOPSIS 

# include <sys/types.h> 

# include <sys/ipc.h> 

# include <sys/msg.h> 



msgop 


int msgsnd ( int msqi d, struct msgbuf *msgp" ,int msgsz,int msgflg ); 
int msgrcv ( int ms q i d, struct msgbuf *msgp,int msgsz,long ms g t y p, int msgflg ); 

DESCRIPTION 

T o send or receive a message, the calling process allocates a structure that looks I ike the following: 
struct msgbuf { 

long mtype; /* message type, must be > 0 */ 
char mtext[1]; /* message data */ 

}; 

but with an array mtext of sizemsgsz, a nonnegative integer value. The structure member mtype must have a strictly positive 
integer value that can beused by the receiving process formessage selection (see the section about msgrcv). 

The calling process must have write access permissions to send and read access permissions to receive a message on the queue. 

The msgsnd system call queues a copy of the message pointed to by the ms gp argument on the message queue whose identifier 
is specified by the value of the msqi d argument. 

The argument ms gf i g specifies the system call behavior if queuing the new message will require more than msg_qbytes in the 
queue. Asserting ipcjiowait, the message will not be sent and the system call fails, returning with errno set to eagain. 
Otherwise the process is suspended until the condition for the suspension no longer exists (in which case the message is sent 
and thesystem call succeeds), or the queue is removed (in which casethesystem call fails with errno set to eidrm), or the 
process receives a signal that has to be caught (in which casethesystem call fails with errno set to eintr). 

Upon successful completion, themessage queue data structure is updated as follows: 
msgjLspid Set to the process D of thecalling process. 

msg_qnum Incremented by 1. 

msg_stime Set to the current time. 

Thesystem call msgrcv reads a message from the message queue specified by msqi d into the msgbuf pointed to bythemsgp 
argument, removing from the queue, on success, the read message. 

The argument ms gsz specifies the maximum size in bytes for the member mtext of the structure pointed to bythemsgp 
argument. If the message text has length greater than ms gsz , then if the ms gf i g argument asserts msg_noerror, the message text 
will be truncated (and the truncated part will be lost); otherwise, the message isn't removed from the queue and thesystem 
call fails, returning with errno set to e 2 big. 

The argument ms gtyp specifies thetypeof message requested as follows: 

If msgtyp iso, themessage on the queue's front isread. 

If ms gtyp is greater than e, the first message on the queue of type ms gtyp is read if msg_except isn't asserted by the ms gf i g 
argument; otherwise the first message on the queue of type not equal to msgtyp will be read. 

If msgtyp islessthan 0 , the first message on the queue with the lowest type less than or equal to the absolute value of ms gtyp 
will be read. 

T he ms gf 1 g argument asserts none, one, or more (OR-ing them) among the following flags: 

ipc_nowait For immediate return if no message of the requested type is on the queue. Thesystem call 

fails with errno Set tO ENOMSG. 

msg_except Used with msgtyp greater than 0 to read the first message on the queue with message type 

that differs from msgtyp. 

T 0 truncate the message text if longer than ms g s z bytes. 



MSG_NOERROR 
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If no message of the requested type is available and ipc_nowait isn't asserted in ms gf i g , the calling process is blocked until one 
of thefollowing conditions occurs: 

A message of the desi red type is placed on the queue. 

The message queue is removed from thesystem. In such a case the system call failswith errno set to eidrm. 

The calling process receives a signal that has to be caught. In such a case the system call failswith errno set to eintr. 

Upon successful completion, themessage queue data structure isupdated as follows: 
msg_irpid Set to the process D of the calling process. 

msg_qnum D ecremented by 1. 

msg_rtime Set to the current time. 



RETURN VALUE 

On afailure, both functions return -i with errno indicating the error; otherwise, msgsnd returnse and msgrvc returns the 
number of bytes actually copied into themtext array. 

ERRORS 

When msgsnd fails, at return errno will beset to one of thefollowing values: 

eagain The message can't be sent due to themsg_qdytes limit for the queue, and ipc_nowait was 

asserted in mgsf i g. 

eacces T h e cal I i n g process h as n o wri te access perm i ssi on s on th e m essage qu eu e. 

efault Theaddress pointed to by msgp isn't accessible. 

eidrm Themessagequeuewasremoved. 

eintr Sleeping on a full message queue condition, the process received a signal that had to be 

caught. 

einval Invalid msqi d value, or nonpositive mt ype value, or invalid msgsz value (less than 0 or greater 

than thesystem value msgmax). 

enomem T he system has not enough memory to make a copy of the supplied msgbut. 

When msgrcv fails, at return errno will beset to one of thefollowing values: 

e 2 big The message text length is greater than msgsz and msg_noerror isn't asserted in ms gf 1 g. 

eacces The calling process has no read access permissions on the message queue. 

efault Theaddress pointed to by msgp isn't accessible. 

eidrm Whiletheprocesswassleepingto receive a message, themessagequeuewasremoved. 

eintr Whiletheprocesswassleepingto receive a message, the process received a signal that had to 

be caught. 

einval Illegal msggi d value, or msgsz lessthanc. 

enomsg ipc_nowait was asserted in ms gf 1 g and no message of the requested type existed on the 

message queue. 


NOTES 

The followings are system limits affecting a msgsnd system call: 

msgmax M aximum size for a message text; the implementation set this value to 4080 bytes. 

msgmnb Default maximum size in bytes of a message queue: policy dependent. The superuser can 

increase thesizeof a message queue beyond msgmnb by amsgcti system call. 

The implementation has no intrinsic limits for the systemwide maximum number of message headers (msgtql) and for the 
systemwide maximum size in bytes of the message pool (msgpool). 
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SEE ALSO 

ipc(5), msgctl(2), msgget(2), msgrcv(2), msgsnd(2) 


Linux 0.99.13,1 N ovember 1993 


msync 

msync — Synchronizes a fi le with a memory map 

SYNOPSIS 

#include <unistd.h> 

#include <sys/mman.h> 

#ifdef_POSIX_MAPPED_FILES 
#ifdef_POSIX_SYNCHRONIZED_IO 

int msync(const void *start, size_t length,int flags); 

#endif 

#endif 


DESCRIPTION 

msync flushes changes made to the in-core copy of a file that was mapped into memory using mmap(2) back to disk. W ithout 
use of this call, there is no guarantee that changes are written back before munmap(2) is called. T o be more precise, the part of 
the file that corresponds to the memory area starting at start and having length length is updated. Then ags argument may 
have the bitSMs_ASYNc, ms_sync, and ms_invalidate set, but not both ms async and ms_sync. ms_async specifies that an update 
be scheduled, but the call returns immediately. ms_sync asks for an update and waitsfor it to complete, msjnvalidate asks to 
invalidate other mappings of the same file (so that they can be updated with the fresh values just written). 


RETURN VALUE 

O n success, e is returned. 0 n error, -i is returned and errno is set appropriately. 


ERRORS 

einval start is not a multiple of pagesize, or any bit other than ms_async ; ms_invalidate 

ms_sync is set in f I ags. 

efault The indicated memory (or part of it) was not mapped. 

C0NF0RMST0 

POSIX.4. 


SEE ALSO 

mma P (2), B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128-129, 389-391. 


Linux 1.3.86,12 April 1996 


munlock 

munlock— Reenables pagi ng for some parts of memory 

SYNOPSIS 


#include <sys/mman.h> 

int munlock(const void *addr , size_t I en); 
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DESCRIPTION 

muniock reenables paging for the memory in the range starting at add r with length i en bytes. All pages that contain a part of 
the specified memory range can after calling muniock be moved to external swap space again by the kernel. 

M emory locks do not stack, that is, pages that have been locked several times by cal Is to miock or miockaii will be unlocked 
by a single call to muniock for the corresponding range or by muniockaii. Pages that are mapped to several locations or by 
several processes stay locked into RAM as long as they are locked at least at one location or by at least one process. 

On POSIX systemson which miock and muniock are available _POSIX_M EM LOCK_RAN GE is defined in <unistd.h> 
and the value pagesize from <iimits.h> indicates the number of bytes per page. 

RETURN VALUE 

On success, muniock returns 0 . 0 n error, -i is returned, errno is set appropriately, and no changes are made to any locks in 
the address space of the process. 

ERRORS 

enomem Some of the specified address range does not correspond to mapped pages in the address 

space of the process. 

einval en wasnota positive number. 

STANDARDS 

POSIX.lb, SVR4 

SEE ALSO 

mlock(2), mlockall(2), munlockall(2). 

Linux 1.3.43, 26 November 1995 


muniockaii 

muniockaii— Reenables paging for calling process 

SYNOPSIS 

#include <sys/mman.h> 
int munlockall(void); 

DESCRIPTION 

muniockaii reenables paging for all pages mapped into the address space of the calling process. 

M emory locks do not stack, that is, pages that have been locked several times by cal Is to miock or miockaii will be unlocked 
by a single cal I to muniockaii. Pages that are mapped to several locations or by several processes stay locked into RAM as long 
as they are locked at least at one location or by at least one process. 

On POSIX systemson which miockaii and muniockaii are available, _posix_memlock isdefined in <uni s t d. h >. 

RETURN VALUE 

O n success, muniockaii returns 0 . 0 n error, -1 is returned and errno is set appropriately. 

STANDARDS 

POSIX.lb, SVR4 
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SEE ALSO 

mlockall(2), mlock(2), munlock(2) 


Linux 1.3.43, 26 November 1995 


nanosleep 

nanosieep— Pauses execution for a specified time 

SYNOPSIS 

#include <time.h> 

int nanosleep(const struct timespec *req, struct timespec *rem); 

DESCRIPTION 

nanosieep delays the execution of the program for at least the time specified in * r eq .The function can return earlier if a signal 
has been delivered to the process. In thiscase, it returns -i, setserrno to eintr, and writes the remaining timeinto the 
structure pointed to by rem unless rem is null. The value of *rem can then be used to call nanosieep again and complete the 
specified pause. 

T he structure t i mes pec is used to specify intervals of time with nanosecond precision. It is specified in <t i me. h> and has the 
form 

struct timespec 
{ 

time_t tv_sec; /* seconds */ 
long tv_nsec; /* nanoseconds */ 

}; 

The value of the nanoseconds field must be in the range 0 to 999 999 999. 

Compared to sieep(3) and usieep(3), nanosieep has the advantage of not affecting any signals; it is standardized by PO SIX, it 
provides higher timing resolution, and it allows to continue a sleep that has been interrupted by a signal more easily. 

ERRORS 

In case of an error or exception, the nanosieep system call returns -i instead of e and setserrno to one of the following values: 

eintr The pause has been interrupted by a nonblocked signal that was delivered to the process. 

The remaining sleep time has been written into *rem so that the process can easily call 
nanosieep again and continue with the pause. 

einval The value in thet v_nsec field was not in the range 0 to 999 999 999 or t v_s ec was negative. 

BUGS 

The current implementation of nanosieep is based on the normal kernel timer mechanism, which has a resolution of 1/HZ s 
(that is, 10ms on Linux/i386 and 1ms on Linux/Alpha). Therefore, nanosieep pauses always for at I east the specified time; 
however, it can take up to 10ms longer than specified until the process becomes runnable again. For the same reason, the 
value returned in case of a delivered signal in *rem is usually rounded to the next larger multiple of 1/HZ s. 

Because some applications require much more precise pauses (for example in order to control sometime-critical hardware), 
nanosieep isalso capable of short high-precision pauses. If the process is scheduled under a real-time policy such as 
s c h e d_ f i fo or schedrr, then pauses of up to 2ms will be performed as busy waits with microsecond precision. 


STANDARDS 

POSlX.lb 
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SEE ALSO 

sleep(3), usleep(3), sched_setscheduler(2), timer_create(2) 


Linux 1.3.85,10 April 1996 


nice 

nice— Changes process priority 

SYNOPSIS 

#include <unistd.h> 
int nice(int i nc); 

DESCRIPTION 

nice addsi nc to the priority for the calling PID. Note that only the superuser may specify a negative increment, or priority 
increase. N otethat internally, a higher number is a higher priority. Do not confuse thiswith the priority scheme as used by 
the nice interface. 

RETURN VALUE 

O n success, 0 is returned. 0 n error, -1 is returned and errno isset appropriately. 

ERRORS 

eperm A nonsuperuser attemptsto do a priority increase, a numerical decrease, by supplying a 

negativei nc. 

C0NF0RMST0 

SVID EXT, AT&T, X/OPEN, BSD 4.3 

SEE ALSO 

nice(l), setpriority(2), fork(2), renice(8) 

Linux, 28 M arch 1992 

oldfstat, oldlstat, oldstat, oldolduname,olduname 

oldfstat, oldlstat, oldstat, oldolduname, olduname —Obsolete system calls 

SYNOPSIS 

O bsolete system calls. 

DESCRIPTION 

The Linux 1.3.6 kernel implements these calls to support old executables. These calls return structures that have grown since 
their first implementations, but old executables must continue to receive old smaller structures. 

Current executables should be linked with current libraries and never use these calls. 

SEE ALSO 

fstat(2), lstat(2), stat(2), uname(2), undocumented(2), unimplemented(2) 


Linux 1.3.6, 22 July 1995 
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open, creat 

open, creat— Open and possibly create a file or device 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/stat.h> 

#include <fcntl.h> 

int open(const char *pat hname,int flags); 

int open(const char *pat hname,int flags,mode_t mode); 

int creat(const char *pathname,mode_t mode); 


DESCRIPTION 

open attempts to open a file and return a file descriptor (a small, nonnegative integer for use in read, write, and so on), 
flags is one of o_rdonly, o_wronly, oro_RDWR, which request opening the file read-only, write-only, or read/write, respectively, 
flags may also be bitwise-oRed with one or moreof the following: 
o_creat If the file does not exist it will becreated. 

o_excl When used with o_creat, if thefi leal ready exists, it is an error and the open will fail. Seethe 

"Bugs" section, though. 

o_noctty If pathname refers to a terminal device— see tty(4>— itwill not become the process's 

controlling terminal a/en if the process does not have one. 
ojtrunc If thefilealready exists, itwill betruncated. 

oappend The file is opened in append mode. Initially, and before each write, the file pointer is 

positioned at the end of the file, as if with lseek. 

o_nonblock or ondelay T he fi le is opened in nonblocking mode. N either the open nor any subsequent operations on 

the file descriptor that is returned will cause the calling process to wait. 
o_sync The file is opened for synchronous I/O. Any writes on the resulting file descriptor will 

block the calling process until the data has been physically written to the underlying 
hardware Seethe "Bugs" section, though. 


Some of these optional flags can be altered using fcnti after the file has been opened. 


mode specifies the permissions to use if a new file is created. It is modified by the process's mask in the usual way: The 
permission of the created file is (mode & ’mask). 


The following symbolic constants are provided for mode: 


S_IRWXU 

S_IRUSR (S_IREAD) 

S_IWUSR (s_iwrite) 

S_IXUSR (s_iexec) 

S_IRWXG 

S_IRGRP 

S_IWGRP 

S_IXGRP 

S_IRWX0 

S_IR0TH 

S_IW0TH 

S_IX0TH 


00700 user (file owner) has read, write and execute permission. 
00400 user has read permission. 

00200 user has write permission. 

00100 user has execute permission. 

00070 group has read, write, and execute permission. 

00040 group has read permission. 

00020 group has write permission. 

00010 group has execute permission. 

00007 others have read, write, and execute permission. 

00004 others have read permission. 

00002 others have write permission. 

00001 others have execute permission. 


mode should always be specified when o_creat isin then ags, and isignored otherwise, 
creat is equivalent to open with f i ags equal to o_creat|o_wronly!o_trunc. 
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RETURN VALUE 

open and creat return the new file descriptor, or -i if an error occurred (in which caseerrno is set appropriately). N otethat 
open can open device-special files, but creat cannot create them— use mknod(2) instead. 

ERRORS 

EEXIST 
EISDIR 
ETXTBSY 

EFAULT 
EACCES 

ENAMETOOLONG 
ENOENT 
ENOTDIR 
EMFILE 
ENFILE 
ENOMEM 
EROFS 
ELOOP 

ENOSPC 

C0NF0RMST0 

SVID, AT&T, POSIX, X/OPEN , BSD 4.3 

BUGS 

o_sync is not currently implemented (as of Linux 0.99pl7). 

T here are many infelicities in the protocol underlying N FS, affecting amongst others o_sync, o_ndelay, and o_append. 

o_excl is broken on N FS filesystems; programs that rely on it for performing locking tasks will contain a race condition. The 
solution for performi ng atomic file locking using a lockfile is to create a unique file on the same ts (for example, incorporat¬ 
ing hostname and PID), useiink(2) to make a link to the lockfile and usestat(2) on the unique file to check if its link 
count has increased to 2 . Do not use the return value of the iink() call. 

SEE ALSO 

read(2), write(2), fcntl(2), close(2), unlink(2), mknod(2), stat(2), umask(2), mount(2), socket(2), socket(2), fopen(3), link(2) 

Linux0.99.7, 21 July 1993 


p a t h n a me already exists and o_creat and o_excl were used. 

pathname refersto a directory and theaccess requested involved writing. 

pathname refers to an executable image which is currently being executed and write access 

was requested. 

p a t h n a me poi nts outsi de your accessi bl e address space. 

The requested access to thefileisnot allowed, or one of the directories in pathname did not 
allow search (execute) permission, 
pathname wastOO long. 

A directory component in pat hname does not exist or isa dangling symbolic link. 

A component used as a directory in pathname is not, in fact, a directory. 

T he process already has the maximum number of fi les open. 

The limit on the total number of files open on the system has been reached. 
Insufficientkernelmemorywasavailable. 

pathname refersto a file on a read-only filesystem and write access was requested, 
pathname contains a reference to a circular symbolic link, that is, a symbolic link whose 
expansion contains a reference to itself. 

pathname was to be created but the device containing pat hname has no room for the new file. 


outb, outw, outl, outsb, outsw, outsi 

outb, outw, outl, outsb, outsw, outsi— Port Output 

inb, inw, ini, insb, insw, insl — Port input 

outb_p, outw_p, outl_p, inb_p, inw_p, inl_p— Pause I/O 

DESCRIPTION 

Thisfamily of functions is used to do low-level port input and output. They are primarily designed for internal kernel use, 
but can beused from user space, given thefollowing information in addition to that given in outb(9). 



personality 



You compile with -o or -02 or something similar. The functions are defined as inline macros and will not be substituted in 
without optimization enabled, causing unresolved references at link time. 

You use ioperm(2) or alternatively ±opi(2) to tell the kernel to allow the user space application to access the I/O ports in 
question. Failure to do this will cause the application to receive a segmentation fault. 

C0NF0RMST0 

outb and friends are hardware specific. The port and value arguments are in the opposite order from most DOS implementa¬ 
tions. 

SEE ALSO 

outb(9), ioperm(2), iopl(2) 

Linux, 29 November!995 


pause 

pause— Waits for signal 

SYNOPSIS 

#include <unistd.h> 
int pause(void); 

DESCRIPTION 

Thepause system call causes the invoking process to sleep until asignal is received. 

RETURN VALUE 

pause always returns -i, and errno is set to erestartnohand. 

ERRORS 

eintr Signal was received. 

conforms™ 

SVID, AT&T, POSIX, X/OPEN , BSD 4.3 

SEE ALSO 

kill(2), select(2), signal(2) 

Linux, 31 August 1995 


personality 

personality— Sets the process execution domain 

SYNOPSIS 

int personality(unsigned long persona); 

DESCRIPTION 

Linux supports different execution domains, or personalities, for each process. Among other things, execution domains tell 
Linux how to map signal numbers into signal actions. The execution domain system allows Linux to provide limited support 
for binaries compiled under other U NI X-like operating systems. 

personality will make the execution domain referenced bypersona the new execution domain of the current process. 
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RETURN VALUE 

On success, persona ismadethenew execution domain and the previouspe r s o n a is returned. On error, -i is returned and 
errno is set appropriately. 

ERRORS 

einval persona does not refer to a valid execution domain. 

FILE 


/usr/include/linux/personality.h 


C0NF0RMST0 

personality is Linux specific. 


Linux2.0, 22July 1996 


phys 

phys— Allows a process to access physical addresses (thiscommand is not implemented) 

SYNOPSIS 

int phys(int physnum, char *virtaddr,longsize, char *physaddr); 

DESCRIPTION 

Warning: Because this function is not implemented as of Linux 0.99.11, it will always return -i and set errno to enosys. 

phys maps arbitrary physical memory into a process's virtual address space, physnum is a number (0-3) that specifies which of 
the four physical spaces to set up. Up to four phys calls can be active at any onetime virtaddr is the process's virtual address, 
size isthe number of bytes to map in. physaddr is the physical address to map in. 

Valid virtaddr and physaddr values are constrained by hardware and must beat an address multiple of the resolution of the 
CPU's memory management scheme. If size is nonzero, size is rounded up to the next M M U resolution boundary. If size is 
0 , any previous phys(2) mapping for that physnum is nullified. 

RETURN VALUE 

On success, 0 is returned. 0 n error, -1 is returned and errno is set appropriately. 

C0NF0RMST0 

version 7 AT&T UNIX 

BUGS 

phys is very machine dependent. 

SEE ALSO 

mmap(2), munmap(2) 


pipe 

pipe-Creates a pipe 


Linux0.99.11, 24July 1993 
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SYNOPSIS 

#include <unistd.h> 
int pipe(int filedes[2]); 

DESCRIPTION 

pipe creates a pair of file descriptors, pointing to a pipe inode, and places them in the array pointed to by filedes. fiiedesio] 
isfor reading, fiiedesm isforwriting. 

RETURN VALUE 

O n success, 0 is returned. 0 n error, -1 is returned and errno is set appropriately. 

ERRORS 

emfile T 00 many file descriptors are in use by the process. 

enfile The system file table is full. 

EFAULT filedes is not valid. 

SEE ALSO 

read(2), write(2), fork(2), socketpair(2) 

Linux 0.99.11 23 July 1993 


profil 

profii— Execution time profile 

SYNOPSIS 

#include <unistd.h> 

int profil(char *buf, int buf s i z ,int offset ,int seale); 

DESCRIPTION 

Under Linux 0.99.11, profil is not implemented in the kernel. Instead, the D L L 4.4.1 libraries provide a user-space 
implementation. 

buf points to buf si z bytes of core Every virtual 10 milliseconds, the user's program counter (PC) is examined: offset is 
subtracted and the result is multiplied by seal e. If this address is in buf, the word pointed to is incremented. 

If seal e is less than 2 or buf s i z iso, profiling is disabled. 

RETURN VALUE 

0 is always returned. 

BUGS 

profii cannot beused on a program that also uses itimerprof itimers. 

Calling profii with an invalid buf will resultin acoredump. 

T rue kernel profiling provides more accurate results. 

SEE ALSO 

gprof(l), setitimer(2), signal(2), sigaction(2) 


Linux0.99.11, 23July 1993 
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ptrace — Process trace 

SYNOPSIS 

#include <sys/ptrace.h> 

int ptrace(int request,int pid,int addr ,int data); 

DESCRIPTION 

ptrace provides a means by which a parent process can control the execution of a child process and examine and change its 
core image. Its primary use is for the implementation of breakpoint debugging. A traced process runs until a signal occurs. 
Then it stops and the parent is notified with wait(2). W hen the process is in the stopped state, its memory can be read and 
written. The parent can also cause the child to continue execution, optionally ignoring the signal which caused stopping. 

The value of the request argument determines the precise action of thesystem call: 

ptrace_traceme This process isto be traced by its parent. The parent should be expecting to trace the chi Id. 

PTRACE_PEEKTEXT, Read word at location addr. 

PTRACE_PEEKDATA 

ptrace_peekusr Read word at location addr in the user area. 

PTRACE_POKETEXT, W riteword at location addr. 

PTRACE_POKEDATA 

ptrace_pokeusr W rite word at location addr in the user area. 

ptrace_syscall, Restart after signal. 

PTRACE_CONT 

ptrace_kill Send the child a sigkill to make it exit. 

ptrace_singlestep Set the trap flag for single stepping. 
ptrace_attach Attach to the process specified in pi d. 

ptrace_detach D etach a process that was previously attached. 

NOTES 

init, the process with processID 1, may notusethisfunction. 

RETURN VALUE 

O n success, 0 is returned. 0 n error, -1 is returned and errno is set appropriately. 

ERRORS 

EPERM 
ESRCH 
EIO 

C0NF0RMST0 

SVID EXT, AT&T, X/OPEN, BSD 4.3 

SEE ALSO 

gdb(l), exec(2), signalf2), wait(2) 


T he specified process (that is, init), cannot be traced orisalready being traced. 
The specified process does not exist. 

Request is not valid. 



Linux0.99.11, 23July 1993 
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quotactl 

quotacti— M anipulatesdisk quotas 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/quota.h> 

int quotactl (int c md, const char *s pec i a I , intid , caddr_t ad d r); 

#include <linux/unistd.h> 

syscall4(int, quotactl, int, c md, const char *, special ,int, id, caddr_t, addr); 

DESCRIPTION 

The quota system defines for each user or group a soft limit and a hard limit bounding the amount of disk space that can be 
used on a given filesystem. The hard limit cannot be crossed. The soft limit can be crossed, but warnings will ensue. 

M oreover, the user cannot be above the soft limit for more than one week (by default) at a time After this week the soft limit 
counts as a hard limit. 

T he quotacti system call manipulates these quotas. Its first argument is of the form 
QCMD(subcmdjtype) 

where type is either usrquota or grpquota (for user quota and group quota, respectively. 

The second argument special is the block special device these quotas apply to. It must be mounted. 

Thethird argument ID isthe user or group ID these quotas apply to (when relevant). 

Thefourth argument, addr , is the address of a data structure, depending on thecommand. 

T he subcmd isoneof the following: 


Q_QUOTAON 

Enables quotas. The addr argument is the pathname of the file containing the quotas for the filesystem. 

Q_QUOTAOFF 

Disables quotas. 

Q_GETQUOTA 

Gets limits and current usage of disk space. The addr argument is a pointer to adqbik structure 
(defined in <sys/quota.h>). 

Q_SETQUOTA 

Sets limits and current usage; addr isas before 

Q_SETQLIM 

Sets limits; addr isas before. 

Q_SETUSE 

Sets usage. 

Q_SYNC 

Syncs disk copy of a filesystem's quotas. 

Q_GETSTATS 

Gets collected stats. 

RETURN VALUE 

On success, quotacti returnsa. On error, -i isreturned and errno is set appropriately. 

ERRORS 

ENOPKG 

The kernel was compiled without quota support. 

EFAULT 

Bad addr value. 

EINVAL 

type is not a known quota type. Or special could not be found. 

ENOTBLK 

special is not a block special device. 

ENODEV 

special cannot be found in the mount table 

EACCES 

The quota file is not an ordinary file. 

EIO 

Cannot read or write the quota file 

EMFILE 

T oo many open files: C annot open quota file. 
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EBUSY 

ESRCH 

EPERM 

CONFORMSTO 

BSD 


read 

read— Readsfrom a file descriptor 

SYNOPSIS 

#include <unistd.h> 

ssize_t read(int fd,void*buf, size_t count); 

DESCRIPTION 

reado attempts to read up to count bytes from fi le descriptor fd into the buffer starting at but. 

If count iso, reado returns 0 and has no other results If count is greater than ssize_max, the result is unspecified. 

RETURN VALUE 

On success, the number of bytes read is returned (0 indicates end of file) and thefile position is advanced by this number. It 
is not an error if this number is smaller than the number of bytes requested; this may happen, for example, because fewer 
bytes are actually available right now (maybe because we were close to end-of-fileor because we are reading from a pipe or 
from a terminal), or because reado was interrupted by a signal. On error, -1 is returned and errno is set appropriately. In this 
case it is left unspecified whether thefile position (if any) changes. 

ERRORS 

eintr Thecall was interrupted by a signal before any data was read. 

eagain N on-blocking I/O has been selected using ojjonblock and no data was immediately avail able for 

reading. 

eio I/O error. Thiswill happen, for example, when the process is in a background process group, tries to 

read from its controlling tty, and it is ignoring or blocking sigttin or its process group isorphaned. 
eisdir f d refers to a di rectory. 

ebadf fd is not a valid file descriptor or is not open for reading. 

einval fd isattached to an object that isunsuitablefor reading. 

efault buf isoutsideyouraccessibleaddressspace. 

Other errors may occur, depending on the object connected to fd. POSIX allows a read that is interrupted after reading some 
data to return -1 (with errno set to eintr) or to return the number of bytes already read. 

CONFORMSTO 

SVID, AT&T, POSIX, X/OPEN, BSD 4.3 

SEE ALSO 

readdir(2), write(2), write(2), fcntl(2), close(2), lseek(2), select(2), readlink(2), ioctl(2), f read(3) 

Linux, 17 January 1996 


q_quotaon was asked, but quota were enabled already. 

q getquota or q_setquota or q_setuse or q_setqlim was asked for a filesystem that didn't have quota 
enabled. 

The process was not root (for the filesystem), and q_getquota was asked for another ID than that of the 
process itself, or anything other than q_getstats or q_sync was asked. 


Linux 1.3.88,14 April 1996 



readlink 

readdir 

readdir— Reads directory entry 

SYNOPSIS 

#include <unistd.h> 

#include <linux/dirent.h> 

#include <linux/unistd.h> 

syscall3(int, readdir, uint, fd, struct dirent *, dirp, uint, count); 
int readdir(unsigned int fd, struct dirent *dirp, unsigned int count); 

DESCRIPTION 

This is not the function you are interested in. Look at readdin(3) for the PO SIX -conforming C library interface. This page 
documents the bare kernel system call interface, which can change, and which is superseded by getdents(2). 

readdir reads one dirent structure from the directory pointed at by fd into the memory area pointed to by di r p . T he 
parameter count is ignored; at most one dirent structure is read. 

Thedirent structure is declared asfollows: 

struct dirent 
{ 

leng d_ino; 
off_t d_off; 

unsigned short d_reclen; 
char d_name [NAME_MAX+1]; 

} 

d_i no is an inode number. d_ of f is the distance from the start of the directory to this di rent. d_reci en is the size of d_ na me , not 
counting the null terminator. d_name is a null-terminated filename 

RETURN VALUE 

On success, i is returned. 0 n end of directory, 0 is returned. On error, -1 is returned and errno is set appropriately. 

ERRORS 

ebadf Invalid file descriptor fd. 

enotdir File descriptor does not refer to a directory. 

C0NF0RMST0 

Thissystem call is Linux specific. 

SEE ALSO 

getdents(2), readdir(3) 

Linux 1.3.6, 22July 1995 

readlink 

readiink— Reads value of a symbolic link 

SYNOPSIS 


/* inode number */ 

/* offset to this dirent */ 

/* length of this d_name */ 

/* file name (null-terminated) */ 



#include <unistd.h> 

int readlink(const char *p a t h, char *buf , size_t bufsiz); 
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DESCRIPTION 

readiink places the contents of the symbolic link path in the buffer buf , which has size buf si z . Readlink does not append a 
nul character to buf. 

RETURN VALUES 

The call returns the count of characters placed in the buffer if it succeeds, or a-i if an error occurs, placing the error code in 
the global variable ermo. 

ERRORS 

ENOTDIR 
EINVAL 
ENAMETOOLONG 

ENOENT 
EACCES 
ELOOP 
EINVAL 
EIO 

EFAULT 

HISTORY 

The readiink function call appeared in BSD 4.2. 

SEE ALSO 

stat(2), lstat(2), symlink(2) 

BSD Man Page, 24July 1993 


A component of the path prefix is not a directory. 

T he pathname contains a character with the high-order bit set. 

A component of a pathname exceeded 255 characters, or an entire path nameexceeded 1023 
characters. 

T he named file does not exist. 

Search permission isdenied for a component of the path prefix. 

T oo many symbolic linkswere encountered in translating the pathname. 

The named file is not a symbolic link. 

An I/O error occurred while reading from thefilesystem. 
buf extends outside the process's allocated address space. 


readv, writev 

readv, writev— Reads or writes a vector 

SYNOPSIS 

#include <sys/uio.h> 

int readv(int fd, const struct iovec * vector , size_t count ); 
int writev(int fd, const struct iovec * vector, size_t count); 
struct iovec { 

ptr_t iovbase; /* Starting address. */ 
size_t i ov_I en; /* Length in bytes. */ 

}; 

DESCRIPTION 

readv reads data from file descriptor f d and puts the result in the buffers described by vector . The number of buffers is 
specified by count . The buffers are filled in the order specified. Operates just like read except that data is put in vector 
instead of a contiguous buffer. 

writev writes data to file descriptor f d , and from the buffers described by vector. The number of buffers is specified by count . 
The buffers are used in the order specified. Operates just like write except that data is taken from vector instead of a 
contiguous buffer. 



readv, write/ 



RETURN VALUE 

On success, readv returnsthe number of bytes read. On success, writev returnsthe number of bytes written. On error, -i is 
returned, and errno is set appropriately. 

ERRORS 

einval An invalid argument was given. For instancecount might be greater than max_iovec, or 0 . fd could 

also be attached to an object that is unsuitable for reading. 

efault Segmentation fault. M ost likely vector orsomeof the i ov.base pointers pointsto memory that is 

not properly allocated. 

ebadf T he file descriptor fd isnotvalid. 

eintr The call was interrupted by a signal before any data was read/written. 

eagain N on-blocking I/O has been selected using o_nonblock and no data was immediately avail able for 

reading. (0 r the file descriptor fd isforan object that is locked.) 
eisdir fd refers to a directory. 

eopnotsup f d refers to a socket or device that does not support reading/writing. 

Other errors may occur, depending on the object connected to f d. 

SEE ALSO 

read(2), write(2), fprintf(3), fscant(2) 

Linux 1.3.86,12 April 1996 


reboot 

reboot— Reboots or disables C trl-t-Alt+D el 

SYNOPSIS 

#include <unistd.h> 

int reboot (int magi c , int magi c_t oo ,int flag); 

DESCRIPTION 

reboot reboots the system or enables/disables C AD. 

If magic =oxf eeidead and magic_too =672274793, the action performed will be based on f I ag. 
If fiag=8xi 234567, a hard reset is performed. 

If fiag=8x89abcdef, CAD is enabled. 

If fiag=e, CAD is disabled and a signal is sent to process ID 1. 

N ote that reboot () does not sync () I 
0 n Iy the su peru ser may use th i s fun cti on. 

RETURN VALUE 

On success, 0 is returned. 0 n error, -1 is returned, and errno is set appropriately. 

ERRORS 

einval Bad magi c numbers orf 1 ag. 

A non-root user has attempted to call reboot. 


EPERM 
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CONFORMSTO 

reboot is Linux specific. 

SEE ALSO 

sync(2), ctrlaltdel(8), halt(8), reboot(8) 

Linux 0.99.10, 28 M arch 1992 


recv, recvfrom,recvmsg 

recv, recvfrom, recvmsg —Receives a message from a socket 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/socket.h> 

int recv(int s, void *buf , intlen, unsigned int flags); 
int recvfrom(int s, void*buf , int len, unsigned int flags, 
struct sockaddr *from, int *f r oml en); 
int recvmsgfint s, struct msghdr *msg, unsigned int flags); 

DESCRIPTION 

W arning: T his isa BSD man page. As of Linux 0.99.11, recvmsg was not implemented. 

recvfrom and recvmsg are used to receive messages from a socket, and may be used to receive data on a socket whether or not 
it isconnection oriented. 

If from is non-nil, and the socket is not connection-oriented, the source address of the message isfilled in. f romi en is a value- 
result parameter, initialized to the size of the buffer associated with from and modified on return to indicate the actual size of 
the address stored there. 

The recv call is normally used only on a connected socket (seeconnect(2)) and is identical to recvfrom with anil from 
parameter. Because it is redundant, it might not be supported in future releases. 

All three routines return the length of the message on successful completion. If a message is too long to fit in the supplied 
buffer, excess bytes might be discarded depending on the type of socket from which the message is received (seesocket(2)). 

If no messages are available at the socket, the receive call waits for a message to arrive—unless the socket is nonblocking (see 
fcnti(2)), in which case the value -i is returned and the external variable errno is set to ewouldblock. The receive calls 
normally return any data available, up to the requested amount, rather than wait for receipt of thefull amount requested; 
this behavior is affected by the socket-level options so_rcvlowat and so_rcvtimeo, described in getsockopt(2). 

T he seiect(2) call may be used to determine when more data arrives. 

T hef i ags argument to a recv call isformed by oring one or more of the values: 
msg_oob Process out-of-band data 

msg__peek Peek at incoming message 

msg_waitall W ait for full request or error 

TheMSG_ooBflag requests receipt of out-of-band data that would not be received in the normal data stream. Some protocols 
place expedited data at the head of the normal data queue; thus this flag cannot be used with such protocols. The msg_peek 
flag causes the receive operation to return data from the beginning of the receive queue without removing that data from the 
queue; thus, a subsequent receive call will return the same data. The msg_waitall flag requests that the operation block until 
thefull request is satisfied. However, thecall might still return less data than requested if a signal iscaught, an error or 
disconnect occurs, or the next data to be received is of a different type than that returned. 



recv, recvfrom, recvmsg 



T he recvmsg call usesamsghdr structure to minimize the number of directly supplied parameters. This structure has the 
following form, as defined in sys/socket.h: 

struct msghdr { 

caddr_t msg_name; /* optional address */ 
u_int msg_namelen; /* size of address */ 
struct iovec *msg_iov; /* scatter/gather array */ 
u_int msg_iovlen; /* # elements in msg_iov */ 
caddr_t msg_control; /* ancillary data, see below */ 
u_int msg_controllen; /* ancillary data buffer len */ 
int msg_flags; /* flags on received message */ 

}; 

H eremsg_name and msg_nameien specify the destination address if the socket is unconnected; msg_namemay be given as a null 
pointer if no names are desired or required. msg_iov and msg_iovien describe scatter gather locations, as discussed in read(2). 
msg_controi, which has length msg_controiien, points to a buffer for other protocol control-related messages or other 
miscellaneous ancillary data. T he messages are of the form 

struct cmsghdr { 

u_int cmsgjen; /* data byte count, including hdr */ 
int cmsg_level; /* originating protocol */ 
int cmsg_type; /* protocol-specific type */ 

/* followed by 

u_char crasg_data[]; */ 

}; 

You could use this, for example, to learn of changes in the data stream in XN S/SPP, or in ISO, to obtain user- 
connection-request data by requesting a recvmsg with no data buffer provided immediately after an accept call. 

Open file descriptors are now passed as ancillary data for afjjnix domain sockets, with cmsg_ievei set to sol_socket and 
cmsg_type Set to SCM_RIGHTS. 

T he msgf lags field is set on return according to the message received. msg_eor indicates end-of-record; the data returned 
completed a record (generally used with sockets of type sock_seqpacket). msg_trunc indicates that the trailing portion of a 
datagram was discarded because the datagram was larger than the buffer supplied. msg_ctrunc indicates that some control 
data was discarded due to lack of space in the buffer for ancillary data. msg_oob is returned to indicate that expedited or out- 
of-band data was received. 

RETURN VALUES 

These calls return the number of bytes received, or -i if an error occurred. 

ERRORS 

EBADF 

enotconn 

enotsock 
ewouldblock 

eintr 
efault 

HISTORY 

These function calls appeared in BSD 4.2. 


The argument s isan invalid descriptor. 

T he socket is associated with a connection-oriented protocol and hasnot been connected (see 
connect(2) and accept(2)). 

T he argument s does not refer to a socket. 

The socket is marked non-blocking, and the receive operation would block, or a receive timeout 
had been set, and thetimeout expired before data was received. 

T he receive was interrupted by delivery of a signal before any data was available. 

T he receive buffer pointer(s) point outside the process's address space. 
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SEE ALSO 

fcntl(2), read(2), select(2), getsockopt(2), socket(2) 
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rename 

rename— C hanges the name or location of a file 

SYNOPSIS 

#include <unistd.h> 

int rename(const char *oI d pa t h , const char *newpat h); 


DESCRIPTION 

rename renames a file, moving it between directories if required. 

Any other hard links to the file (as created using link) are unaffected. 

If newpat h al ready exi sts i t wi 11 be automatically overwritten (subject to a few conditions— see the "Errors" section), so that 
thereisno pointat which another process attempting to access newpat h will find it missing. 

If newpat h exists but the operation fails for some reason or the system crashes, rename guarantees to leave an instance of 
newpat h in place. 

H owever, when overwriting there will probably be a window in which both oi dpat h and newpat h refer to thefile being 
renamed. 

If oi d pat h refers to a symbolic link, the link will be renamed; if newpat h refers to a symbolic link, the I ink will be overwritten. 

RETURN VALUE 

O n success, 0 is returned. 0 n error, -1 is returned, and errno isset appropriately. 


ERRORS 

EISDIR 

EXDEV 

ENOTEMPTY 

EBUSY 

EINVAL 

EMLINK 

ENOTDIR 

EFAULT 

EACCES 


EPERM 


ENAMETOOLONG 

ENOENT 

ENOMEM 

EROFS 


newpat h is an existing directory, but oi dpat h is not a directory, 
oi dpat h and newpat h are noton the same filesystem, 
newpat h is a non-empty directory. 

newpat h exists and isthecurrent working directory or root directory of some process. 

An attempt wasmadeto make a directory a subdirectory of itself. 

oi dpat h already has the maximum number of I inks to it, or it was a directory and the directory 

containing newpat h has the maximum number of links. 

A component used as a directory in oi dpat h or newpat h is not, in fact, a directory. 

01 dpat h or newpat h points outside your accessible address space. 

Write access to the directory containing 0 1 dpat h or newpat h is not allowed for the process's effective 
UID, or one of the directories in oi dpat h or newpat h did not allow search (execute) permission, or 
oi dpat h was a directory and did not allow write permission (needed to update the .. entry). 

The directory containing oi dpat h has the sticky bit set, and the process's effective UID is neither the 
UID ofthefileto be deleted nor that of the di rectory containi ng it, or the filesystem containing 
pat hna me does not support renaming of the type requested, 
ol dpat h Or newpat h W 3 S tOO long. 

A directory component in 01 dpat ti or newpat h does not exist or is a dangling symbolic link. 
Insufficientkernelmemorywasavailable. 

Thefileison a read-only filesystem. 



rmdir 



eloop oi dpath or newpat h contains a reference to a circular symbolic link; that is, a symbolic link whose 

expansion contains a reference to itself. 

enospc The device containing the file has no room for the new directory entry. 

C0NF0RMST0 

POSIX, BSD 4.3, ANSI C 

BUGS 

Currently (Linux 0.99pl7), most of the filesystems except M inixwill not allow any overwriting renames involving directories. 
You get eexist if you try. 

On N FS filesystems, you cannot assume that just because the operation failed, the file was not renamed. If the server does 
the rename operation and then crashes, the retransmitted RPC, which will be processed when theserver isup again, causesa 
failure. The application is expected to deal with this. See imk(2) for a similar problem. 

SEE ALSO 

link(2), unlink(2), symlink(2), mv(l), link(8) 

Linux0.99.7, 24July 1993 


rmdir 

rmdir— D eletes a directory 

SYNOPSIS 

#include <unistd.h> 

int rmdir(const char *pat hname); 


DESCRIPTION 

rmdir deletes a directory, which must be empty. 


RETURN VALUE 

O n success, e is returned. 0 n error, -i is returned, and errno isset appropriately. 


ERRORS 

EPERM 

EFAULT 

EACCES 

EPERM 

ENAMETOOLONG 

ENOENT 

ENOTDIR 

ENOTEMPTY 

EBUSY 

ENOMEM 

EROFS 

ELOOP 


T hef iI esystem containing pat hname does not support the removal of directories, 
pat h n a me poi nts outsi de your accessi bl e address space. 

Write access to the directory containing pat hna me was not allowed for the process's effective U ID, 
or one of the directories in pathname did notallow search (execute) permission. 

The directory containing pat hna me has the sticky bit (s_isvtx) set, and the process's effective U ID is 
neither theU ID ofthefileto be deleted nor that of the directory containing it. 
pat hname wastOO long. 

A directory component in pat hname does not exist or isa dangling symbolic link, 
pathname, or a component used as a directory in pathname, is not, in fact, a directory, 
pathname contains entries other than .and ... 

pat hname is the current working directory or root directory of some process. 

Insufficientkernelmemorywasavailable. 

pat hname refers to a file on a read-only filesystem. 

pat hname contains a reference to a circular symbolic link; that is, a symbolic link containing a 
reference to itself. 
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CONFORMSTO 

SVID, AT&T, POSIX, BSD 4.3 

BUGS 

Infelicities in the protocol underlying N FS can cause the unexpected disappearance of directories that are still being used. 

SEE ALSO 

rename(2), mkdir(2), chdir(2), unlink(2), rindir(l), rra(l) 

Linux0.99.7, 24July 1993 

sched_get_priority_max, sched_get_priority_min 

sched_get_priority_max, sched_get_priority_min —Gets Static priority range 

SYNOPSIS 

#include <sched.h> 

int sched_get_priority_max(int policy); 
int_sched_get_priority_min(int policy); 

DESCRIPTION 

sched_get_prionityjnax returns the maximum priority value that can beused with the scheduling algorithm identified by 
poi icy. sched_get_priority_min returns the minimum priority value that can beused with the scheduling algorithm 
identified by p o i i c y . Supported policy values are sched_fifo, schedrr, and schedjjther. 

Processes with numerically higher priority values are scheduled before processeswith numerically lower priority values. 
Therefore the value returned by sched_get_priority_max will be greater than the value returned by sched_get_priority_min. 

Linux allows the static priority value range 1 to 99 for sched_fifo and schedrr, and the priority 0 for sched_other. 
Scheduling priority ranges for the various policies are not alterable. 

The range of scheduling priorities may vary on other POSIX systems, so it is a good idea for portable applications to use a 
virtual priority range and map it to the interval given by sched_get_priority_max and sched_get_priority_min. PO SIX .lb 
requires a spread of at least 32 between the maximum and the minimum values for sched_fifo and sched_rr. 

POSIX systems on which sched_get_priority_max and sched_get_priority_min are available define 
_POSIX_PRIORITY_SCHEDULING in <unistd.h>. 

RETURN VALUE 

On success, sched_get_priority_max and sched_get_priority_min return themaximum and minimum priority values for the 
named scheduling policy. On error, -i is returned, and errno is set appropriately. 

ERRORS 

einval The parameter policy does not identify a defined scheduling policy. 

STANDARDS 

POSlX.lb (formerly POSIX.4) 

SEE ALSO 

sched_setscheduler(2), sched_getscheduler(2), sched_setparam(2), sched_getparam(2) 

sched_setscheduier(2) has a description of the Linux scheduling scheme. 



xhed_rr_get_interval 



Programming for theReal World— PO SIX.4 by Bill 0. Gallmeister, 0 'Reilly S< Associates, Inc., ISBN 1-56592-074-0 
IEEE Std 1003.lb-1003 (POSlX.lbstandard) 

ISO/IEC 9945-1:1996 

Linux 1.3.81,10 April 1996 


sched_rr_get_interval 

sched_rr_get_intervai— Gets the sched_rr interval forthenamed process 

SYNOPSIS 

#include <sched.h> 

int sched_rr_get_interval(pid_t pI d, struct timespec *tp); 
struct timespec { 

time_t tv_sec; /* seconds */ 
long tv_nsec; /* nanoseconds */ 

}; 

DESCRIPTION 

sched_rr_get_intervai writes into the t i mespec structure pointed to by tp the round-robin time quantum for the process 
identified by pi d. If pi d iso, the time quantum for the calling process is written into *tp. The identified process should be 
running under thescHED RR scheduling policy. 

Theround robin time quantum valueisnot alterable under Linux 1.3.81. 

POSIX systems on which sched_rr_get_interval is available define _POSIX_PRIORITY_SCHEDULING in <unistd.h>. 

RETURN VALUE 

On success, sched_rr_get_intervai returns 0 . 0 n error, -i is returned, and errno isset appropriately. 

ERRORS 

esrch The process whose ID ispi d could not befound. 

enosys Thesystem call isnotyet implemented. 

STANDARDS 

POSlX.lb (formerly POSIX.4) 

BUGS 

As of Linux 1.3.81, sched_rr_get_intervai returns with error enosys, because sched rr has not yet been fully implemented or 
tested properly. 

SEE ALSO 

sched_setscheduier(2) has a description of the Linux scheduling scheme. 

Programming for theReal World— POSIX.4 by Bill 0. Gallmeister, 0 'Reilly S< Associates, Inc., ISBN 1-56592-074-0 
IEEE Std 1003.lb-1993 (POSlX.lbstandard) 

ISO/IEC 9945-1:1996 


Linux 1.3.81,10 April 1996 
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sched_setparam, schedjetparam 

sched_setparam, sched_getparan — Sets and get scheduling parameters 

SYNOPSIS 

#include <sched.h> 

int sched_setparam(pid_t pid, const struct sched_param *p); 
int sched_getparam(pid_t pid, struct sched_param *p); 
struct sched_param { 

int sched pri ori ty; 


}; 

DESCRIPTION 

sched_setparani sets the scheduling parameters associated with the scheduling policy for the process identified by pi d. If pi d is 
0 , the parameters of the current process are set. The interpretation of the parameter p depends on the selected policy. 
Currently, the following three scheduling policies are supported under Linux: sched_fifo, sched_rr, and sched other. 

sched_getparam retrieves the scheduling parameters for the process identified by pi d. If pi d iso, the parameters of the current 
process are retrieved. 

sched_setparani checks the validity of p for the scheduling policy of the process. T he parameter p->sched_priority must lie 
Within the range given by sched_get_priority_min and sched_get_priority_max. 

POSIX systemson which sched_setparam and sched_getparam are available define_POSIX_PRIORITY_SCHEDULING in <unistd.h>. 

RETURN VALUE 

0 n success, sched_setparam and sched_getparam return 0 . On error, -i is returned, and errno isset appropriately. 

ERRORS 

ESRCH 
EPERM 

EINVAL 

STANDARDS 

POSlX.lb (formerly POSIX.4) 

SEE ALSO 

sched_setscheduler(2), sched_getscheduler(2), sched_get_priority_max(2), sched_get_prionity_min(2), nice(2), 
setpriority(2), getpriority(2) 

sched_setscheduier(2) has a description of the Linux scheduling scheme. 

Programming for the Real World— POSIX.4 by Bill 0. Gallmeister, 0 'Reilly S< Associates, Inc., ISBN 1-56592-074-0 
IEEE Std 1003.lb-1993 (POSlX.lbstandard) 

ISO/IEC 9945-1:1996 


The process whose ID ispid could not be found. 

The calling process does not have appropriate privileges. The process calling sched_setparam needs 
an effective U ID equal to the U ID orUID of the process identified by p i d, or it must be a 
superuser process. 

The parameter p does not make sense for the current scheduling policy. 


Linux 1.3.81,10 April 1996 
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sched_setscheduler, schedjetscheduler 

sched_setscheduier, sched_getscheduien— Sets and gets scheduling algorithm/parameters 

SYNOPSIS 

#include <sched.h> 

int sched_setscheduler(pid_t pi d ,intp o I i cy , const struct sched_param *p); 
int sched_getscheduler(pid_t pid); 
struct sched_param { 

int sched_priority; 


}; 

DESCRIPTION 

sched_setscheduier sets both the scheduling policy and the associated parameters for the process identified by pi d. If pi d iso, 
the scheduler of the calling process will beset. The interpretation of the parameter p depends on the selected policy. 
Currently, the following three scheduling policies are supported under Linux: sched_fifo, sched_rr, and sched other; their 
respective semantics are described in the followi ng section. 

sched_getscheduier queries the scheduling policy currently applied to the process identified by pi d. If pi d iso, the policy of 
the calling processwill be retrieved. 

SCHEDULING POLICIES 

The scheduler is the kernel part that decides which runnable process will be executed next by the CPU. The Linux scheduler 
offers three different scheduling policies, one for normal processes and two for real-time applications. A static priority value, 
schedpri ori t y, is assigned to each process, and this value can be changed only via system calls Conceptually, the scheduler 
maintains a list of runnable processes for each possibles c hed_ pr i ori i y value, and sched.pri ori ty can have a value in the 
range 0 to 99. T o determine the process that runs next, the Linux scheduler looks for the non-empty list with the highest 
static priority and takes the process at the head of this list. The scheduling policy determines, for each process, where it will 
be inserted into the list of processes with equal static priority and how itwill move inside this list. 

sched_other isthe default universal time-sharing scheduler policy used by most processes; schedfifo and schedrr are 
intended for special, time-critical applications that need precise control over the way in which runnable processes are selected 
for execution. Processes scheduled with sched_other must be assigned the static priority 0; processes scheduled under 
sched_fifo or sched_rr can have a static priority in the range 1 to 99. Only processes with superuser privileges can get astatic 
priority higher than 0 and can therefore be scheduled under sched_fifo or sched_rr. The system calls sched_get_priority_min 
and sched_get_priority_max can be used to find out the valid priority range for a scheduling policy in a portable way on all 
PO SIX .lb-conforming systems. 

All scheduling is preemptive: If a process with ahigher static priority gets ready to run, the current processwill be preempted 
and returned into its wait list. The scheduling policy determines the ordering within the list of runnable processes only 
among those with equal static priority. 

SCHEDJIFO: FIRST IN-FIRST OUT SCHEDULING 

sched_fifo can only be used with static priorities higher than 0, which means that when a sched_fifo process becomes 
runnable, itwill always preempt immediately any currently running normal sched_other process, schedfifo isasimple 
scheduling algorithm without time si icing. 

For processes scheduled under the sched_fifo policy, the following rules are applied: A sched_fifo process that has been 
preempted by another process of higher priority will stayatthehead of the list for its priority and will resume execution as 
soon as all processes of higher priority are blocked again. When a sched_fifo process becomes runnable, itwill be inserted at 
the end of the list for its priority. A call to sched_setscheduier or sched_setparam will put the sched fifo process identified by 
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pi d at the end of the list if it was runnable A process calling sched_yieid will be put at the end of the list. N o other a/ents 
will move a process scheduled under the sched_fifo policy in the wait list of runnable processes with equal static priority. A 
schedfifo process runs until itisblocked by an I/O request, it ispreempted by a higher-priority process, or it calls 

sched_yield. 

SCHED_RR: ROUND-ROBIN SCHEDULING 

sched rr is a simple enhancement of sched_fifo. Everything described in the preceding section for schedfifo also applies to 
sched_rr, except that each process is only allowed to run for a maximum time quantum. If a sched rr process has been 
running for a time period equal to or longer than the time quantum, it will be put at the end of the list for its priority. A 
sched_rr process that has been preempted by a higher-priority process and subsequently resumes execution as a running 
process will complete the unexpired portion of its round-robin time quantum. The length of the time quantum can be 
retrieved by sched_rr_get_interval. 

SCHED OTHER: DEFAULT LINUX TIME-SHARING SCHEDULING 

sched_other can only be used at static priority 0. sched_other is the standard Linux time-sharing scheduler that is intended 
for all processes that do not require special static-priority real-time mechanisms. The process to run is chosen from the static 
priority 0 list based on a dynamic priority that is determined only inside this list. The dynamic priority is based on the nice 
level (set by the nice or setpriority system call) and is increased for each time quantum the process is ready to run but is 
denied to run by the scheduler. This ensures fair progress among all sched_other processes. 

RESPONSE TIME 

A blocked high-priority process waiting for the I/O has a certain response time before it is scheduled again. The device driver 
writer can greatly reduce this response time by using a slow interrupt interrupt handler, as described in request irq(9). 

MISCELLANEOUS 

Child processes inherit the scheduling algorithm and parameters across a fork. 

M emory locking is usually needed for real-time processes to avoid paging delays; this can be done with miock or miockaii. 

Because a non-blocking endless loop in a process scheduled under sched_fifo or sched rr will block all processes with lower 
priority forever, a software developer should always keep available on the console a shell scheduled under a higher static 
priority than the tested application. This will allow an emergency kill of tested real-time applications that do not block or 
terminate as expected. Because sched fifo and sched^rr processes can preempt other processes forever, only root processes 
are allowed to activate these policies under Linux. 

POSIX systems on which sched_setscheduier and sched_getscheduier areavailabledefine _posix_priority_scheduling in 
<unistd.h>. 

RETURN VALUE 

On success, sched_setscheduier returns 0 . 0 n success, sched_getscheduier returnsthe policy for the process (a non-negative 
integer). On error, -i is returned, and errno is set appropriately. 

ERRORS 

ESRCH 
EPERM 

EINVAL 

STANDARDS 

POSlX.lb (formerly POSIX.4) 


The process whose ID ispi d could not be found. 

The calling process does not have appropriate privileges. Only root processes are allowed to activate 
the sched_fifo and sched_rr policies. The process calling sched_setscheduier needs an effective 
UID equal to the EU ID orUID of the process identified by pi d, or it must be a superuser process. 
The scheduling policy is not one of the recognized policies, or the parameter p does not make sense 
for the policy. 



sled, FD_CLR, FDJSSET, FD_SET, FD_ZERO 



BUGS 

As of Linux 1.3.81, schedrr has not yet been tested carefully and might not behave exactly as described or required by 
POSlX.lb. 


SEE ALSO 

sched_setparam(2), sched_getparam(2), sched_yield(2), sched_get_priority_max(2), sched_get_priority_min(2), nice(2), 
setpniority(2), getpriority(2), mlockall(2), munlockall(2), mlock(2), munlock(2). 

Programming for theReal World- PO SIX.4 by Bill 0. Gallmeister, 0 'Reilly & Associates, Inc., ISBN 1-56592-074-0 
IEEE Std 1003.lb-1003 (POSlX.lbstandard) 

ISO/IEC 9945-1:1996— This isthe new 1996 revision of POSIX.1, which containsin one single standard PO SIX.1(1990), 
PO SIX .lb(1993), PO SI X.lc( 1995), and PO SIX .li(1995). 

Linux 1.3.81,10 April 1996 


sched_yield 

sched_yieid— Yields the processor 

SYNOPSIS 

#include <sched.h> 
int sched_yield(void); 

DESCRIPTION 

A process can relinquish the processor voluntarily without blocking by calling sched_yieid. The process will then be moved 
to the end of the queue for its static priority and a new process gets to run. 

N ote: If the current process is the only process in the highest priority list at that time this process will continue to run after a 
Call to sched_yield. 

POSIX systems on which sched_yieid isavailabledefine _posix_priority_scheduling in <unistd.h>. 

RETURN VALUE 

On success, sched_yieid returns 0 . On error, -i isreturned, and ermoissetappropriately. 

STANDARDS 

POSlX.lb (formerly POSIX.4) 

SEE ALSO 

sched_setscheduier(2) for a description of Linux scheduling 

Programming for theReal World— POSIX.4 by Bill 0. Gallmeister, 0 'Reilly S< Associates, Inc., ISBN 1-56592-074-0 
IEEE Std 1003.1b-1993 (POSlX.lbstandard) 

ISO/IEC 9945-1:1996 

Linux 1.3.81,10 April 1996 


select, FD_CLR, FDJSSET, FD_SET, FD_ZER0 

select, fd_clr, fd_isset, fd_set, fd_zero— Synchronous I/O multiplexing 
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SYNOPSIS 

#include <sys/time.h> 

#include <sys/types.h> 

#include <unistd.h> 

int select(int n,fd_set *readfds ,fd_set *wri tefds ,fd_set *exceptfds, 
struct timeval *t i me o ut ); 

FD_CLR(int fd,fd_set *set); 

FD_ISSET(int fd,fd_set *set); 

FD_SET(int f d ,fd_set *s et ); 

FD_ZERO(fd_set *set ) 

DESCRIPTION 

select waits for a number of fi le descri ptorsto change status. 

Three independent sets of descri ptors are watched. Those listed in r eadf ds will be watched to see if characters become 
available for reading, those in wr i tefds will be watched to see if it is okay to immediately write on them, and those in 
exceptfds will be watched for exceptions. On exit, the sets are modified in place to indicate which descriptors actually 
changed status. 

Four macros are provided to manipulate the sets. fd_zero will clear a set. fd_set and fd_clr add or remove a given descriptor 
from a set. fd_isset tests to see if a descriptor is part of the set; this is useful after select returns 

n isthehighest-numbered descriptor in any of the three sets, plus 1. 

ti meout is an upper bound on the amount of time elapsed before select returns It may be 0 , which causes select to return 
immediately. If timeout isNun (no timeout), select can block indefinitely. 

RETURN VALUE 

On success, select returns thenumber of descriptors contained in the descriptor sets, which may be 0 if thetimeout expires 
before anything interesting happens. On error, -1 isreturned, and errno is set appropriately; the sets and t i meout become 
undefined, so do not rely on their contents after an error. 

ERRORS 

EBADF 
EINTR 
EINVAL 
ENOMEM 

NOTES 

Some code calls select with all three sets empty, n =0, and a non-null timeout; this is a fairly portable way to sleep with 
subsecond precision. 

On Linux, ti meout is modified to reflect the amount of time not slept; most other implementations do not do this. This 
causes problems both when Linux code that reads ti meout is ported to other operating systems and when code is ported to 
Linux that reuses a struct timevai for multiple seiectsin a loop without reinitializing it. Considerti meout to beundefined 
after select returns. 

EXAMPLE 

#include <stdio.h> 

#include <sys/time.h> 

#include <sys/types.h> 

#include <unistd.h> 


An invalid file descriptor was given in oneof the sets. 

A non-blocked signal was caught, 
n is negative. 

select was unable to al locate memory for i nternal tables. 
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int 

main(void) 

{ 

fd_set rfds; 
struct timeval tv; 
int retval; 

/* Watch stdin (fd 0) to see when it has input. */ 
FD_ZERO(&rfds); 

FD_SET(0, &rfds); 

/* Wait up to five seconds. */ 
tv.tv_sec = 5; 
tv.tv_usec = 0; 

retval = select(1, &rfds, NULL, NULL, &tv); 

/* Don't rely on the value of tv now! */ 

if (retval) 

printf("Data is available now.nn"); 

/* FD_ISSET(0, &rfds) will be true. */ 

else 

printf("No data within five seconds.nn"); 
exit(0); 

} 

SEE ALSO 

accept(2), connect(2), read(2), recv(2), send(2), write(2) 


Linux 1.2,11 February 1996 


semctl 

semcti— Semaphore-control operations 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/ipc.h> 

#include <sys/sem.h> 

int semctl ( int se mid, int semnun,int c md, union semun arg ); 

DESCRIPTION 

Thefunction performs the control operation specified by c md on the semaphore set (or on thesuimn-nth semaphore of the 
set) identified by semi d. The first semaphore of the set is indicated by a value of 0 for semun. 

T he type of a r g istheunion 
union semun { 

int val; /* used for SETVAL only */ 

struct semid_ds *buf; /* for IPC_STAT and IPC_SET */ 

ushort *array; /* used for GETALL and SETALL */ 

}; 

Legal values for cmd are 

ipc_stat Copies info from the semaphore set data structure into the structure pointed to by arg .but. The 

argument semn um is ignored. The calling process must have read access privileges on the semaphore set. 
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IPC_SET 


IPC_RMID 

GETALL 

GETNCNT 

GETPID 

GETVAL 

GETZCNT 

SETALL 


SETVAL 


Writes the values of some members of thesemid_ds structure pointed to by a r g . but to the semaphore 

set data structure, updating also its sem_ctime member. Considered members from the user-supplied 

struct semid_ds pointed to by arg.buf are 

sem_perm.uid 

sem_perm.gid 

sem_perm.mode /* only lowest 9-bits */ 

The calling process's effective user ID must be super-user, creator, or owner of the semaphore set. The 
argument semnum is ignored. 

Removes the semaphore set and its data structures immediately, awakening all waiting processes (with 
an error return and errno set to EID R M ). The calling process's effective user ID must be super-user, 
creator, or owner of the semaphore set. The argument semnum isignored. 

Returns semvai for all semaphores of the set into ar 9 .array. The argument semnum isignored. The 
calling process must have read access privileges on the semaphore set. 

The system call returns the value of semncnt for thesemno-th semaphore of the set (that is, the number 
of processes waiting for an increase of semvai for thesemno-th semaphore of the set). The calling 
process must have read access privileges on the semaphore set. 

The system call returns the value of sempid for thesemno-th semaphore of the set (that is, thepid of the 
process that executed the last semop call for thesemno-th semaphore of the set). The calling process 
must have read access privileges on the semaphore set. 

The system call returns the value of semvai for thesemno-th semaphore of the set. The calling process 
must have read access privileges on the semaphore set. 

The system call returns the value of semzcnt for thesemno-th semaphore of the set (that is, the number 
of processes waiting for thesemvai of thesemno-th semaphore of the set to become 0). The calling 
process must have read access privileges on the semaphore set. 

Sets semvai for all semaphores of the set usi ng a r g. array, updati ng also the sem_ctime member of the 
semid_ds structure associated with the set. U ndo entries are cleared for altered semaphores in all 
processes. Processes sleeping on the wait queue are awakened ifsornesemvai becomes 0 or increases. 
The argument semnum isignored. The calling process must have alter access privileges on the semaphore 
set. 

Sets the value of semvai to a r g .vai for the s emnu m-th semaphore of the set, updating also thesem_ctime 
member of thesemid ds structure associated to the set. The undo entry iscl eared forthealtered 
semaphore in all processes. Processes sleeping on the wait queue are awakened if semvai becomes 0 or 
increases. The calling process must have alter access privileges on the semaphore set. 


RETURN VALUE 

On fail, the system call returns- 1 , with errno indicating the error. Otherwise the system call returns a non-negative value, 
depending on cmd, as follows: 

GETNCNT The value of semncnt. 

GETPID The value of sempid. 

GETVAL The value of semvai. 

GETZCNT The value of semzcnt. 


ERRORS 

Forafailing return, errno will be set to one of the following values: 
eaccess The calling process has no access permissions needed to execute cmd. 

efault The address pointed to by a r g . but or ar 9 .array isn't accessible 

eidrm The semaphore set was removed. 

Invalid valueforcmd orsemid. 


EINVAL 



semget 



eperm The argument cmd has the value ipc_set oriPC_RMiD, but the calling process's effective user ID has 

insufficient privileges to execute the command. 

erange The argument cmd hasthe value setall or setval, and the value to which semvai has to beset (for some 

semaphore of the set) is less than 0 or greater than the implementation value semvmx. 

NOTES 

TheiPc_iNFo, sem_stat, and sem_info control callsareused by the ±pcs(l) program to provide information on allocated 
resources. In thefuture these can be modified as needed or moved to a proc filesystem interface. 

The following system limit on semaphore sets affects a semcti call: 

semvmx M aximum value for semvai; implementation dependent (32767). 

SEE ALSO 

ipc(5), shmget(2), shmat(2), shmdt(2) 

Linux 0.99.13,1 N ovember 1993 


semget 

semget— Gets a semaphore set identifier 

SYNOPSIS 

# include <sys/types.h> 

# include <sys/ipc.h> 

# include <sys/sen.h> 

int semget ( key_t key, int nsems ,int semflg ); 

DESCRIPTION 

This function returns the semaphore set identifier associated with the value of the argument key. A new set of nsems 
semaphores is created if key has the value ipc_private or key isn't ipc_private, if no existing message queue is associated to 
key, and if ipc_creat is asserted in semf i g (that is, semfig& ipc_creat isn't 0). The presence in semf i g of the fields ipc_creat 
and ipc_excl pi ays the same role, with respect to the existence of the semaphore set, as the presence of o_creat and o_excl in 
the mode argument of theopen(2) system call—that is, themsgget function fails if semf i g asserts both ipc_creat and ipc_excl 
and a semaphore set already exists for key. 

Upon creation, the lower 9 bits of the argument semf i g define the access permissions (for owner, group, and others) to the 
semaphore set in the same format, and with the same meaning, as for the access permissions parameter in theopen(2) or 
creat(2) system call (although theexecute permissions are not used by thesystem, and theterm write permissions, for a 
semaphore set, effectively means alter permissions). 

Furthermore, while creating, thesystem call initializes the system semaphore set data structure semid_ds as follows: 

■ sem_perm.cuid and sem_perm.uid are set to the effective user ID of the calling process. 

■ sem_perm.cgid and sem_perm.gid are set to the effective group ID of thecalling process. 

■ Thelowest-order9 bits of sem_perm.mode aresettothelowest-order9 bits of s emf i g. 

■ sem_nsems iSSCt to the Value Of ns ems. 

■ sem_otime iSSCt to 0. 

■ sem_ctime isset to the current time. 

The argument nsems can beO (a "don't care") when thesystem call isn't create(2). Otherwise, nsems must be greater than 0 
and less or equal to the maximum number of semaphores per semid (semmsl). 

If the semaphore set already exists, the access permissions are verified, and a check is made to see if it is marked for destruc¬ 
tion. 
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RETURN VALUE 

If successful, the return value will be the semaphore set identifier (a positive integer); otherwise it will be-i, with errno 
indicating the error. 

ERRORS 

For a failing return, errno will be set to one of the following values: 

eacces A semaphore set exists for key, but the calling process has no access permissions to the set. 

eexist A semaphore set exists for key, and semfi g was asserting both ipc_creat and ipc_excl. 

eidrm T he semaphore set is marked to be deleted. 

enoent N o semaphore set exists for key, and semtig wasn't asserting ipc_creat. 

enomem A semaphore set has to be created, but the system does not have enough memory for the new data 

structure. 

enospc A semaphore set has to be created, but the system limit for the maxi mum number of semaphore 

sets (semmni) or the system-wide maximum number of semaphores (semmns) would be exceeded. 

NOTES 

ipc_private isn't a flag field but a key_t type If this special value is used for key, the system call ignores everything but the 
lowest-order 9 bits of semfi g and creates a new semaphore set (on success). 

The followings are limits on semaphore set resources affecting a semget call: 
semmni System-wide maximum number of semaphore sets; policy dependent. 

semmsl M aximum number of semaphores per semid; implementation dependent (500 currently). 

semmns System-wide maximum number of semaphores; policy dependent. A value greater than 

semmslxsemmni makes it i rrelevant. 

BUGS 

Use of ipc_private doesn't inhibit other processes' access to the allocated semaphore set. 

As for the files, there is currently no intrinsic way for a process to ensure exclusive access to a semaphore set. Asserting both 
ipc_creat and ipc_excl in semfi g only ensures (on success) that a new semaphore set will be created; it doesn't imply 
exclusive access to the semaphore set. 

The data structure associated with each semaphore in the set isn't initialized by the system call. In order to initialize those 
data structures, you have to execute a subsequent call to semcti(2) to perform a setval or asETAn command on the 
semaphore set. 

SEE ALSO 

ftok(3), ipc(5), semctl(2), semop(2) 

Linux 0.99.13,1 N ovember 1993 

semop 

semop— Semaphore operations 

SYNOPSIS 

# include <sys/types.h> 

# include <sys/ipc.h> 

# include <sys/sem.h> 

int semop ( int semid,struct sembuf *sops, unsigned nsops ); 




sm op 



DESCRIPTION 

Thefunction performs operations on selected members of the semaphore set indicated by s e mi d. Each of thensops elements 
in thearray pointed to by sops specifies an operation to be performed on a semaphore by a struct sembut including the 
following members: 

short sem_num; /* semaphore number: 0 = first */ 
short sem_op; /* semaphore operation */ 
short sem_flg; /* operation flags */ 

Flags recognized in sem_fig are ipc_nowait and semjjndo. If an operation asserts semjjndo, it will be undone when the process 
exits 

The system call semantic assures that the operations will be performed if and only if all of them will succeed. Each operation 
is performed on thesem_num-th semaphore of the semaphore set, where the first semaphore of the set issemaphore 0 and is 
one of the following three 

■ If sem_op is a positive integer, the operation adds this value to semvai. Furthermore, if sem_undo is asserted for this 
operation, the system updates the process undo count for this semaphore. The operation always goes through, so no 
process sleeping can happen. The calling process must have alter permissions on the semaphore set. 

■ If sem_op is 0 , the process must have read access permissions on the semaphore set. If semvai Is 0 , the operation goes 
through. Otherwise, if ipc_nowait is asserted in semjig, the system call fails (undoing all previous actions performed), 
with ermo setto eagain. Otherwise, semzcnt isincremented by 1, and the process sleeps until oneof the following 
occurs 

■ semvai becomes 0 , at which time the value of semzcnt is decremented. 

■ The semaphore set is removed, causing the system call to fail with errno setto eidrm. 

■ The calling process receives a signal that has to be caught; which causes the value of semzcnt to be decremented and 
the system call to fail with errno setto eintr. 

■ If sem_op islessthan 0, the process must have alter permissions on the semaphore set. If semvai isgreater than or equal to 
the absolute value of sem_op, the absolute value of sem_op i s su btracted by semvai. Furthermore, if semjjndo isasserted for 
this operation, thesystem updates the process undo count for this semaphore Then the operation goes through. 
Otherwise, if ipc_nowait isasserted in semtig, thesystem call fails (undoing all previous actions performed), with errno 
setto eagain. Otherwise, semncnt isincremented by 1 and the process sleeps until one of the following occurs: 

■ semvai becomes greater than or equal to the absolute value of sem_op, at which time the value of semncnt is 
decremented, the absolute value of sem_op is subtracted from semvai and, if semjjndo isasserted for this operation, 
thesystem updates the process undo count forthissemaphore. 

■ The semaphore set is removed from thesystem: thesystem call fails with errno setto eidrm. 

■ The calling process receives a signal that has to be caught; the value of semncnt is decremented, and thesystem call 
fails with errno Set tO EINTR. 

In case of success, thesempid member of the structure sem for each semaphore specified in thearray pointed to by sops is set 
to the process ID of the calling process. Furthermore both sem_otime and sem_ctime are set to the current time. 

RETURN VALUE 

If successful, thesystem call returns®; otherwise it returns-i, with errno indicating the error. 

ERRORS 

For a failing return, errno will be set to oneof the following values: 

e 2 big The argument ns ops isgreater than semopm, the maximum number of operations allowed per system 

call. 

eacces T he calling process has no access permissions on the semaphore set as required by one of the specified 

operations. 

eagain An operation could not go through, and ipc_nowait was asserted in itssemj i g. 

efault Theaddress pointed to by sops isn't accessible 
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efbig For some operation, the value of sem_num is less than 0 or greater than or equal to the number of 

semaphores in the set. 

eidrm The semaphore set was removed. 

eintr Sleeping on await queue, the process received a signal that had to be caught. 

einval The semaphore set doesn't exist, or semi d islessthan 0, ornsops has a non-positive value. 

enomem T he sem_fig of some operation asserted semjjndo, and the system does not have enough memory to 

allocate theundo structure. 

erange For some operation, semop-Hsemvaiis is greater than semvmx, the implementation-dependent maximum 

value for semval. 


NOTES 

T he sem_undo structures of a process aren't inherited by its chi Id on execution of a tork(2) system call. They are instead 
inherited by the substituting process resulting from the execution of the exec(2) system call. 

T he following are limits on semaphore set resources affecting asemop call: 

semopm M aximum number of operations allowed for onesemop call; policy dependent. 

semvmx M aximum allowable value for semvai; implementation dependent (32767). 

The implementation has no intrinsic limits for the adjust on exit maximum value (semaem), the system-wide maximum 
number of undo structures (semmnu), or the per-process maxi mum number of undo entries system parameters. 

BUGS 

The system maintains a per-process sem_undo structure for each semaphore altered by the process with undo requests. Those 
structures are free at process exit. 0 ne major cause for unhappiness with the undo mechanism is that it does not fit in with 
the notion of having an atomic set of operations in an array of semaphores. Theundo requests for an array and each 
semaphore therein might have been accumulated over many semopt calls Should the process sleep when exiting, orshould all 
undo operations be applied with the ipcjiowait flag in effect? Currently those undo operations that go through immediately 
are applied, and those that require a wait are ignored silently. Therefore harmless undo usage is guaranteed with private 
semaphores only. 

SEE ALSO 

ipc(5), semctl(2), semget(2) 

Linux 0.99.13,1 N ovember 1993 


send, sendto,sendmsg 

send, sendto, sendmsg— Sends a message from a socket 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/socket.h> 

int send(int s, const void *msg,int len, unsigned int flags); 
int sendto(int s, const void *msg, int len, unsigned int flags, 
const struct sockaddr *to, int tolen); 
int sendmsg(int s, const struct msghdr *msg , unsigned int flags); 

DESCRIPTION 

W arning: T his isa BSD man page. As of Linux 0.99.11, sendmsg was not implemented. 

send, sendto, and sendmsg are used to transmit a message to another socket, send may be used only when the socket is in a 
connected state, whereas sendto and sendmsg may be used at any time. 



setfcgf'd 



The address of the target is given by to, with toi en specifying its size. The length of the message is given by i en. If the 
message is too long to pass atomically through the underlying protocol, the error emsgsize is returned, and the message is not 
transmitted. 

N o indication of failure to deliver is implicit in a send. Locally detected errors are indicated by a return value of -i. 

If no message space is available at the socket to hold the message to be transmitted, send normally blocks, unless the socket 
has been placed in non-blocking I/O mode. The seiect(2) call may be used to determine when it is possible to send more 
data. 

T hef i ags parameter may include one or more of the following: 

#define MSG_OOB 0x1 /* process out-of-band data */ 

#define MSG_DONTROUTE 0x4 /* bypass routing, use direct interface */ 

Theflag msg_oob isused to send out-of-band dataon sockets that support this notion (for example sock_stream); the 
underlying protocol must also support out-of-band data. msg_dontroute is usually used only by diagnostic or routing 
programs. 

Seerecv(2) for a description of themsghdr structure 

RETURN VALUES 

The call returns the number of characters sent, or-i if an error occurred. 

ERRORS 

EBADF 
ENOTSOCK 
EFAULT 
EMSGSIZE 

EWOULDBLOCK 
ENOBUFS 

ENOBUFS 

HISTORY 

These function calls appeared in BSD 4.2. 

SEE ALSO 

fcntl(2), recv(2), select(2), getsockopt(2), socket(2), write(2) 

BSD Man Page, 24July 1993 


An invalid descriptor was specified. 

The arguments is not a socket. 

An invalid user space address was specified for a parameter. 

The socket requires that message be sent atomically, and the size of the message to be sent made 
thisimpossible 

The socket is marked non-blocking, and the requested operation would block. 

The system was unable to allocate an internal buffer. The operation might succeed when buffers 
become available. 

The output queuefor a network interface was full. This generally indicates that the interface has 
stopped sending, but it might be caused by transient congestion. 


setfsgid 

setfsgid— Sets group identity used for fi lesystem checks 

SYNOPSIS 

int setfsgid( u id_t fsgid); 

DESCRIPTION 

setfsgid sets the group ID that the Linux kernel uses to check for all accesses to the filesystem. N ormally, the value of f sgi d 
will shadow the value of the effective group ID. In fact, whenever the effective group ID is changed, f sg d will also be 
changed to the new value of the effective group ID. 
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An explicit call to setfsgid is usually only used by programs such as the Linux N FS server that need to change what group 
ID isused for file access without a corresponding change in thereal and effective group IDs. A change in the normal group 
ID s for a program such as the N FS server is a security hole that can expose it to unwanted signals from other group IDs. 

setfsgid will succeed only if the caller is the superuser or iffsgi d matches either the real group ID, effective group ID, saved 
group ID, or the current value of fsgi d. 

RETURN VALUE 

On success, the previous value of fsgi d is returned. 0 n error, the current value of fsgi d is returned. 

C0NF0RMST0 

setfsgid is Linux specific. 

BUGS 

N o error messages of any kind are returned to the caller. At the very least, eperm should be returned when the cal I fails. 

SEE ALSO 

setfsuid(2) 

Linux 1.3.15, 6 August 1995 


setfsuid 

setfsuid— Sets user identity used for filesystem checks 

SYNOPSIS 

int setfsuid(uid_t f suid); 

DESCRIPTION 

setfsuid setsthe user I D that the Linux kernel uses to check for all accesses to the filesystem. N orm ally, the value of f sui d 
will shadow the value of the effective user ID. In fact, whenever the effective user ID is changed, f sui d will also be changed 
to the new value of the effective user ID. 

An explicit call to setfsuid is usually used only by programs such as the Linux N FS server that need to change what user ID 
isused for file access without a corresponding change in thereal and effective user IDs. A change in the normal user IDsfor a 
program such as the N FS server is a security hole that can expose it to unwanted signals from other user IDs. 

setfsuid will succeed only if the caller isthe superuser or if f s u i d matches either the real user ID, effective user ID, saved user 
ID, or the current value of f sui d. 

RETURN VALUE 

On success, the previous value of f sui d is returned. 0 n error, the current value of f sui d is returned. 

C0NF0RMST0 

setfsuid is Linux specific. 

BUGS 

N o error messages of any kind are returned to the caller. At the very least, eperm should be returned when the cal I fails. 

SEE ALSO 

setfsgid(2) 


Linux 1.3.15, 6Augustl995 



sApgid, getpgid, stpgrp, getpgrp 
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setgid 

setgid— Sets group identity 

SYNOPSIS 

#include <unistd.h> 
int setgid(gid_t gi d); 

DESCRIPTION 

setgid sets the effective group ID of the current process. I f the caller is the superuser, thereal and saved group ID s are al so 
set. 

Under Linux, setgid is implemented like sysv, with saved ids. This allows a setgid (other than root) program to drop all its 
group privileges, do some unprivileged work, and then re-engage the original effective group ID in a secure manner. 

If the user is root or the program is setgid root, special care must betaken. The setgid function checkstheeffectivegid of 
the caller and, if it is that of the superuser, all process-related group ID s are set to gi d. After this has occurred, it is impossible 
for the program to regain root privileges. 

RETURN VALUE 

On success, 0 isreturned. On error, -1 isreturned, and errno is set appropriately. 

ERRORS 

eperm Theuser is not the superuser, and gi d does not match the effective or saved group ID of the calling process. 

C0NF0RMST0 

System V 

SEE ALSO 

getgid(2), setregid(2), setegid(2) 

Linux 1.1.36, 29July 1994 


setpgid, getpgid, setpgrp, getpgrp 

setpgid, getpgid, setpgrp, getpgrp— Set^getS process group 

SYNOPSIS 

#include <unistd.h> 

int setpgid(pid_t pi d, pid_t pgid); 

pid_t getpgid(pid_t pid); 

int setpgrp(void); 

pid_t getpgrp(void); 

DESCRIPTION 

setpgid sets the process group ID of the process specified bypid topgid. Ifpid isO, the process ID of the current process is 
used. If pgi d isO, the process ID of the process specified by pi d is used. 

getpgid returns the process group ID of the process specified by pi d. If pi d isO, the process ID of the current process is used. 
In theLinuxDLL 4.4.1 library, setpgrp simply calls setpgid(0,0). 
getpgrp is equivalent to getpgid(O). 
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Process groups are used for distribution of signals and by terminals to arbitrate requests for their input; processes that have 
the same process group as the terminal are foreground and may read, whereas others will block with a signal if the/ attempt 
to read. 

These cal Is are thus used by programs such ascsh(l) to create process groups in implementing job control. The tiocgpgrp 
and tiocspgrp cal Is described in termios(4) are used to get/set the process group of the control terminal. 

RETURN VALUE 

On success, setpgid and setpgrp return 0 . 0 n error, -1 is returned, and errno isset appropriately, 
getpgid returns a process group on success. On error, -1 is returned, and errno isset appropriately, 
getpgrp always returns the current process group. 

ERRORS 

einval pgi d is less than 0. 

eperm Various permission violations. 

esrch pi d does not match any process. 

C0NF0RMST0 

Thefunctions setpgid and getpgrp conform to POSIX.1. Thefunction setpgrp isfrom BSD 4.2.1 haveno information on 
the source Of getpgid. 

SEE ALSO 

getuid(2), setsid(2), tcsetpgrp(3), termios(4) 

Linux 1.2.4,15 April 1995 


setregid,setegid 

setregid, setegid— Sets real and/or effective group ID 

SYNOPSIS 

#include <unistd.h> 

int setregid(gid_t rgid, gid_t egid); 

int setegid(gid_t egid); 

DESCRIPTION 

setregid sets real and effective group ID s of the current process. Unprivileged users may change the real group ID to the 
effective group ID, and vice versa. 

Prior to Linux 1.1.38, the saved ID paradigm, when used with setregid or setegid, was broken. Starting at 1.1.38, it is also 
possi ble to set the effective group ID from the saved user ID. 

0 nly the superuser may make other changes. 

Supplying a value of -1 for either the real or effective group ID forces the system to leave that ID unchanged. 

Currently (libc-4.x.x), setegid (egi d ) is functionally equivalent to setregid )-1 , egid). 

If the real group ID is changed or the effective group ID isset to a value not equal to the previous real group ID, the saved 
group ID will beset to the new effective group ID. 

RETURN VALUE 

On success, 0 is returned. On error, -1 isreturned, and errno isset appropriately. 
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ERRORS 

eperm Thecurrent process is not the superuser, and changes other than swapping the effective group ID 

with the real group ID, setting one to the value of the other, or setting the effective group ID to the 
value of the saved group ID was specified. 

HISTORY 

Thesetregid function call appeared in BSD 4.2. 

C0NF0RMST0 

BSD 4.3 


SEE ALSO 

getgid(2), setgid(2) 


Linux 1.1.38, 2 August 1994 


setreuid,seteuid 

setreuid, seteuid— Sets real and / or effective user ID 

SYNOPSIS 

#include <unistd.h> 

int setreuid(uid_t ruid, uid_t euid); 

int seteuid(uid_t euid); 

DESCRIPTION 

setreuid sets real and effective user IDs of thecurrent process. Unprivileged users may change the real user ID to the 
effective user ID, and vice versa. 

Prior to Linux 1.1.37, thesaved ID paradigm, when used with setreuid or seteuid, was broken. 

Starting at 1.1.37, it is also possible to set the effective user ID from thesaved user ID. 

0 nly the superuser may make other changes. 

Supplying a value of-i for either the real or effective user ID forces the system to leave that ID unchanged. 

Currently (libc-4.x.x), seteuid (eui d ) is functionally equivalent to setreuid (■ i, euid). 

If the real user ID is changed or the effective user ID is set to a value not equal to the previous real user ID, thesaved user ID 
will be set to the new effective user ID. 

RETURN VALUE 

O n success, 0 is returned. 0 n error, -1 is returned, and errno isset appropriately. 

ERRORS 

eperm Thecurrent process is not the superuser, and changes other than swapping the effective user ID 

with the real user ID, setti ng one to the value of the other, or setti ng the effecti ve user ID to the 
value of thesaved user ID was specified. 

HISTORY 

Thesetreuid function call appeared in BSD 4.2. 

C0NF0RMST0 

BSD 4.3 
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SEE ALSO 

getuid(2), setuid(2) 


Linux 1.1.38, 2 Augustl994 


setsid 

setsid— Creates a session and sets the process group ID 

SYNOPSIS 

#include <unistd.h> 
pid_t setsid(void); 

DESCRIPTION 

setsid( ) creates a new session if the calling process is not a process group leader. The calling process is the leader of the new 
session, the process group leader of the new process group, and has no controlling tty. The process group ID and session ID 
of the calling process are set to the PI D of the calling process. The calling process will be the only process in this new process 
group and in this new session. 

RETURN VALUE 

It returns the session ID of the calli ng process. 

ERRORS 

On error, -i will be returned. The only error that can happen is eperm, which is returned when the process group ID of any 
process equals the PI D of the calling process. Thus, in particular, setsid fails if the calling process is already a process group 
leader. 

NOTES 

A process group leader is a process with process group ID equal to its PI D. In order to be sure that setsid will succeed, fork, 
and exit, and havethechild do setsido. 

C0NF0RMST0 

POSIX 


SEE ALSO 

setpgid(2), setpgrp(2) 


27 August 1994 
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setuid— Sets user identity 

SYNOPSIS 

#include <unistd.h> 
int setuid(uid_t ui d); 

DESCRIPTION 

setuid sets the effective user ID of the current process. If the caller is the superuser, the real and saved user ID s are also set. 
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Under Linux, setuid is implemented like sysv, with saved ids. This allows a setuid (other than root) program to drop all its 
user privileges, do some unprivileged work, and then re-engage theoriginal effectiveuser ID in a secure manner. 

If the user is root or the program issetuid root, special care must betaken. The setuid function checksthe effective UID of 
the caller, and, if it is the superuser, all process-related user ID s are set to u i d . After this has occurred, it is impossible for the 
program to regain root privileges. 

RETURN VALUE 

O n success, 0 is returned. 0 n error, -1 is returned, and errno isset appropriately. 

ERRORS 

eperm T he user is not the superuser, and ui d does not match the effective or saved user ID of the calling 

process. 

C0NF0RMST0 

System V 

SEE ALSO 

getuid(2), setreuid(2), seteuid(2) 

Linux 1.1.36 29 July 1994 


setup 

setup— Sets up devices and filesystems mount root fi lesystem 

SYNOPSIS 

#include <unistd.h> 
syscall0(int, setup); 
int setup(void); 

DESCRIPTION 

setup is called once from within unux/init/main.c. It calls initialization functionsfor devices and filesystems configured into 
the kernel and then mounts the root filesystem. 

N 0 user process may call setup. Any user process, even a process with superuser permission, will receive eperm. 

RETURN VALUE 

setup always returns -1 for a user process. 

ERRORS 

eperm Always, for a user process. 

C0NF0RMST0 

T his function is Linux specific. 

Linux 1.2.9, 3 May 1996 
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shmcti— Shared memory control 
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SYNOPSIS 

#include <sys/ipc.h> 

#include <sys/shm.h> 

int shmctl(int s hmi d,int c md, struct shmid ds *buf); 

DESCRIPTION 

shmcti () allows the user to receive information on ashared memory segment, settheowner, group, and permissions of a 
shared memory segment, or destroy a segment. The information about the segment identified by s h mi d is returned in a 
s h mi d_ds structure: 
struct shmid_ds { 

struct ipc_perm shm_pern; /* operation perms */ 
int shm_segsz; /* size of segment (bytes) */ 

time_t shm_atime; /* last attach time */ 

time_t shm_dtime; /* last detach time */ 

time_t shm_ctime; /* last change time */ 

unsigned short shm_cpid; /* pid of creator */ 
unsigned short shm_lpid; /* pid of last operator */ 
short shm_nattch; /* no. of current attaches */ 

/* the following are private */ 

unsigned short shm_npages; /* size of segment (pages) */ 
unsigned long *shm_pages; 

struct shm_desc *attaches; /* descriptors for attaches */ 

}; 

Thefieldsin themernbershm_perm can beset: 

struct ipc_perm 
{ 

key_t key; 

ushort uid;/‘owner euid and egid */ 
ushort gid; 

ushort cuid; /* creator euid and egid */ 
ushort egid; 

ushort mode; /* lower 9 bits of access modes */ 
ushort seq; /* sequence number */ 

}; 

T he following c md s are available: 

ipc_stat Used to copy the information about the shared memory segment into the buffer, buf . The user 

must have read access to the shared memory segment. 

ipc_set Used to apply the changes the user has made to theui d, gi d, or mode members of theshm_perms 

field. Only the lowest 9 bits of mode are used. T h e s h m_ c t i me member is also updated. The user 
must be the owner, the creator, or the superuser. 

ipc_rmid Used to mark the segment as destroyed. It will actually be destroyed after the last detach. (That is, 

when thes hm_ na 11 c h member of the associated structu re s h mi djs iszero.)Theuser must be the 
owner, the creator, or the superuser. 

The user must ensure that a segment is eventually destroyed; otherwise the pages that were faulted in will remain in memory 
or swap. 

In addition, the superuser can prevent or allow swapping of ashared memory segment with the following c md s: (Linux only) 

shm_lock Prevents swapping of ashared memory segment. The user must fault in any pages that are required 

to be present after locking is enabled. 

shmjjnlock Allows the shared memory segment to be swapped out. 

TheiPc_iNFO, shm_stat, and shm_info control callsareused by the ipcs(l) program to provide information on allocated 
resources. In thefuture, these may be modified as needed or moved to a proc filesystem interface. 
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SYSTEM CALLS 

fork() 
exec() 
exit() 

RETURN VALUE 

0 is returned on success; -i on error. 

ERRORS 

On error, errno will be set to one of thefollowing: 

eaccess Returned if ipc_stat is requested and shm_perm.modes does not allow read access for msqid. 

efault T he argument cmd has the value ipc_set or ipc_stat, but the address pointed to by buf isn't 

accessible 

einval Returned if shmid is not a valid identifier, or cmd is not a valid command. 

eidrm Returned if shmid points to a removed identifier. 

eperm Returned if ipc_set or ipc_rmid is attempted, if the user is not the creator, the owner, or the 

superuser, and if the user does not have permission granted to his group or to the world. 

SEE ALSO 

shmget(2), shmop(2) 

Linux 0.99.11, 28 November 1993 

shmget 

shmget— Allocates a shared memory segment 

SYNOPSIS 

#include <sys/ipc.h> 

#include <sys/shm.h> 

int shmget(key_t key, int size, int shmflg); 

DESCRIPTION 

shmget () returns the identifier of the shared memory segment associated with the value of the argument key. A new shared 
memory segment, with its size equal to the rounding up of si ze to a multiple of page_size, is created if key has the value 
ipc_private or if key isn't ipcj’rivate, if no shared memory segment is associated to key, and if ipc_creat is asserted in 
shmflg (that is, shmfig& ipc_creat isn't 0). The presence in shmfig iscomposed of 

ipc_creat Creates a new segment. If this flag is not used, shmget o will find the segment associated with key, 

check to see if the user has permission to receive the shmid associated with the segment, and ensure 
the segment is not marked for destruction. 
ipc_excl U sed with ipc_creat to ensure failure if the segment exists. 

mode_fiags (lowest 9 bits) Specifiesthe permissionsgranted to the owner, group, and world. Presently, the 

execute permissions are not used by the system. 

If a new segment is created, the access permissions from shmflg are copied into theshm_perm member of the shmid_ds 
structure that defines the segment. Following istheshmid_ds structure 

struct shmid_ds { 

struct ipc_perm shm_perm; /* operation perms */ 
int shm_segsz; /* size of segment (bytes) */ 


After atorko, the child inherits the attached shared memory segments 

After an execo, all attached shared memory segments are detached (not destroyed). 

On exit (), all attached shared memory segments are detached (not destroyed). 
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time_t shm_atime; /* last attach time */ 

time_t shm_dtime; /* last detach time */ 

time_t shm_ctime; /* last change time */ 

unsigned short shm_cpid; /* pid of creator */ 
unsigned short shm_lpid; /* pid of last operator */ 
short shm_nattch; /* no. of current attaches */ 


struct ipc_perm 
{ 

key_t key; 

ushort uid; /* owner euid and egid */ 
ushort gid; 

ushort cuid; /* creator euid and egid */ 
ushort egid; 

ushort mode; /* lower 9 bits of shmflg */ 
ushort seq; /* sequence number */ 

}; 

Furthermore, while creating, thesystem call initializes the system shared memory segment data structure shmid_ds as follows: 

■ shm_perm.cuid and shm_perm. uid are set to the effective user ID of the calling process. 

■ shm_perm.cgid and shm_perm.gid are set to the effective group ID of thecalling process. 

■ Thelowest-order9 bits of shm_perm.mode aresettothelowest-order9 bit of shmflg. 

■ shm_segsz iSSS to the value Of si ze. 

■ shm_lpid, shm_nattch, shmatime, and shm_dtime are Set to 0 . 

■ shm_ctime isset to the current time. 

If the shared memory segment already exists, the access permissions are verified, and a check is made to see if it is marked for 
destruction. 

SYSTEM CALLS 

fork() 
exec() 
exit() 

RETURN VALUE 

A valid segment identifier, shmid, is returned on success, -i on error. 

ERRORS 

On failure, errno is set to one of the following: 

einval Returned if shmmin is greater than size, ifsize is greater than shmmax, or if si ze is greater than the 

size of the segment. 

eexist Returned if ipc_creat \ ipcjxcl was specified and the segment exists. 

eidrm Returned if the segment is marked as destroyed or was removed. 

enospc Returned if all possible shared memory ID shavebeen taken (shmmni) or if allocating a segment of 

therequested sizewould cause the system to exceed thesystem-widelimiton shared memory 
(shmall). 

enoent Returned if no segment exists for the given key , and ipc_creat was not specified. 

eacces Returned if the user does not have permission to access the shared memory segment. 

enomem Returned if no memory could be allocated for segment overhead. 


After atorko, the child inherits the attached shared memory segments 

After an execo, all attached shared memory segments are detached (not destroyed). 

On exito, all attached shared memory segments are detached (not destroyed). 
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NOTES 

ipc_private isn't a flag field but a key_t type If this special value is used for key, the system call ignores everything but the 
lowest order 9 bits of s h mf i g and creates a new shared memory segment (on success). 

The following are limits on shared memory segment resources affecting a shmget call: 
shmall System-wide maximum of shared memory pages; policy dependent. 

shmmax M aximum size in bytes, for a shared memory segment; implementation dependent (currently 

4MB). 

shmmin M inimum size, in bytes, for a shared memory segment; implementation dependent (currently 1 

byte, although page_size isthe effective minimum size). 

shmmni System-wide maximum number of shared memory segments; implementation dependent (currently 

4096). 

The implementation has no specific limits for the per-process maximum number of shared memory segments (shmseg). 

BUGS 

Use of ipc_private does not inhibit other processes' access to the allocated shared memory segment. 

As for the files, there is currently no intrinsic way for a process to ensure exclusive access to a shared memory segment. 
Asserting both ipccreat and ipc_excl in s hmf i g only ensures (on success) that a new shared memory segment will be 
created; it doesn't imply exclusive access to the segment. 

SEE ALSO 

ftok(3), ipc(5), shmctl(2), shmat(2), shmdt(2) 

Linux 0.99.11, 28 November 1993 
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shmop— Shared memory operations 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/ipc.h> 

#include <sys/shm.h> 

char *shmat ( intshmid, char *shmaddr , intshmflg ); 
int shmdt ( char *shmaddr); 

DESCRIPTION 

The function shmat attaches the shared memory segment identified by shmid to the data segment of the calling process. The 
attaching address is specified by shmaddr with one of the following criteria: 

■ If shmaddr iso, the system tries to find an unmapped region in the range 1-1.5GB, starting from the upper value and 
coming down from there. 

■ If shmaddr isn't 0 and shm rnd is asserted in shmtig, the attach occurs at the address equal to the rounding down of 
shmaddr to a multiple of shmlba. Otherwise, shmaddr must be a page-aligned address at which the attach occurs. 

If shm rdonly i s asserted in shmf i g, the segment is attached for reading, and the process must have read access permissions to 
thesegment. Otherwise the segment is attached for read and write, and the process must have read and write access 
permissions to thesegment. There is no notion of a write-only shared memory segment. 

T he brk value of the calli ng process is not altered by the attach. T he segment will automatically be detached at process exit. 
The same segment may be attached as a read and as a read-write segment, more than once in the process's address space. 
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On asuccessful shmat call, thesystam updates the members of the structure shmid ds associated to theshared memory 
segment asfollows: 

■ shm_atime isset to the current time. 

■ shm_ipid is set to the process ID of the calling process. 

■ shm_nattch is incremented by 1. 

N ote that the attachment will also succeed if theshared memory segment is marked to be deleted. 

The function shmdt detaches from the calling process's data segment theshared memory segment located at the address 
specified by shmaddr. T he detaching shared memory segment must be one among the currently attached ones (to the 
process's address space) with shmaddr equal to the value returned by its attaching shat call. 

On asuccessful shmdt call, thesystem updates the members of the structure shmidds associated to theshared memory 
segment asfollows: 

■ shm dtime isset to the current time. 

■ shm_ipid is set to the process ID of the calling process. 

■ shm_nattch is decremented by 1. If it becomes 0 and the segment is marked for deletion, the segment is deleted. 

The occupied region in the user space of the calling process is unmapped. 

SYSTEM CALLS 

torko After a fork() , the child inherits the attached shared memory segments. 

execo After an execo, all attached shared memory segments are detached (not destroyed). 

exito On exito, all attached shared memory segments are detached (not destroyed). 

RETURN VALUE 

On afailure, both functions return -i with errno indicating the error; otherwise, shmat returns the address of the attached 
shared memory segment, and shmdt returns 0 . 

ERRORS 

When shmat fails, at return errno will beset to one of the following values: 
eacces Thecallingprocesshasnoaccesspermissionsfortherequested attach type 

einval Invalid sh mi d value, unaligned (that is, not page-aligned and shmjnd was not specified) or invalid 

shmaddr value, or failing attach atprk. 

enomem Could notallocatememoryforthedescriptororforthepagetables. 

Thefunction shmdt can fail only if there is no shared memory segment attached atshmaddr; in such acase, errno will be set to 
einval at return. 

NOTES 

On executing a tork(2) system call, thechild inherits all the attached shared memory segments. 

Theshared memory segments attached to a process executing anexec(2) system call will not be attached to the resulting 
process. 

The following is a system parameter affecting a shmat system call: 

shmlba Segments low-boundary address multiple. M ust be page aligned. For the current implementation, 

the shmbla value is page_size. 

The implementation has no intrinsic limit to the per-process maximum number of shared memory segments (shmseg) 

SEE ALSO 

ipc(5), shmctl(2), shmget(2) 


Linux 0.99.13, 28 Novemberl993 



sigaction, a'gprocmask, sigpending, agauspend 
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shutdown— Shuts down part of a full-duplex connection 

SYNOPSIS 

#include <sys/socket.h> 
int shutdown(int s,int how); 

DESCRIPTION 

The shutdown call causes all or part of a full-duplex connection on the socket associated with s to be shut down. If how is 0 , 
further receives will be disallowed. If how isi, further sends will be disallowed. If how is 2 , further sends and receives will be 
disallowed. 

RETURN VALUE 

0 n success, 0 is returned. 0 n error, -1 is returned, and errno isset appropriately. 

ERRORS 

ebadf s is not a valid descriptor. 

enotsock s is a fi le, not a socket. 

enotconn T he specified socket is not connected. 

HISTORY 

The shutdown function call appeared in BSD 4.2. 

SEE ALSO 

connect(2), socket(2) 

BSD M an Page; 24 July 1993 

sigaction, sigprocmask,sigpending,sigsuspend 

sigaction, sigprocmask, sigpending, sigsuspend—POSIX signal-handling functions. 

SYNOPSIS 

#include <signal.h> 

int sigaction(int signum, const struct sigaction *act , struct sigaction *oldact); 
int sigprocmask(int how, const sigset_t *set , sigset_t *oIdset ); 
int sigpending(sigset_t *set); 
int sigsuspend(const sigset_t ‘mask); 

DESCRIPTION 

The sigaction system call is used to change the action taken by a process on receipt of a specific signal, 
si gnu m specifies the signal and can beany valid signal except sigkill and sigstop. 

If act is non-null, the new action for signal signum is installed from act . If oi dact is non-null, the previous action is saved in 

0 1 d a c t. 

The sigaction structure is defi ned as 

struct sigaction { 

void (*sa_handler)(int); 
sigset_t sajnask; 
int sa_flags; 
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void (*sa_restorer)(void); 

} 

sajiandier specifies the action to be associated with si gnum and can be sig_dfl for the default action, sig_ign to ignore this 
signal, or a pointer to a signal-handling function. 

sa_mask gives a mask of signals that should be blocked during execution of the signal handler. In addition, thesignal that 
triggered the handler will be blocked unless the sa_nodefer or sa_nomask flag isused. 

sa_f lags specifies a set of flags that modify the behavior of the signal-handling process. It is formed by the bitwise 0 R of zero 
or more of the following: 

sa_nocldstop If si gnum issiGCHLD, do not receive notification when child processes stop (that is, when 

child processes receive one of sigstop, sigtstp, sigttin, orsiGnou). 
sa_oneshot orsA_RESETHAND Restores the signal action to the default state oncethe signal handler has been called. 

(This is the default behavior of thesignai( 2 ) system call.) 

sa_restart Provides behavior compatiblewith BSD signal semantics by making certain system calls 

restartable across si gnals 

sa_nomask or sajiodefer D oes not prevent thesignal from being received from within its own signal handler. 

T he sa_restorer element is obsolete and should not be used. 

Thesigprocmask call is used to change the list of currently blocked signals. The behavior of the call is dependent on the value 
of how, as follows: 

sig_block The set of blocked signals is the union of the current set and the set argument. 

sigjjnblock The signals in set are removed from the current set of blocked signals. It is legal to 

attempt to unblock a signal that is not blocked. 
sig_setmask The set of blocked signals is set to the argument set. 

If oi dset is non-null, the previous value of thesignal mask is stored in oi dset. 

Thesigpending call allows the examination of pending si gnals (those that have been raised while blocked). Thesignal mask 
of pending signals is stored inset. 

Thesigsuspend call temporarily replaces thesignal mask for the process with that given by mask and then suspends the 
process until a signal is received. 

RETURN VALUES 

sigaction, sigprocmask, sigpending, and sigsuspend return 0 on success and -1 on error. 

ERRORS 

einval An invalid signal was specified. This will also be generated if an attempt is made to 

change theaction for sigkill or sigstop, which cannot be caught. 
efault act, oi dact, set , or o i dset points to memory that is not a valid part of the process 

address space. 

eintr System call was interrupted. 

NOTES 

It is not possible to block sigkill or sigstop with thesigprocmask call. Attempts to do so will be silently ignored. 

Setting sigchld to sig_ign provides automatic reaping of child processes. 

T he PO SIX spec only defi nes sa_nocldstop. U se of other sa flags is non- portable. 

The sa_resethand f I ag i s co mpati bl e w i th th e S V R 4 f I ag of th e sam e n am e. 
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ThesA_NODEFER flag is compatible with theSVR4 flag of the same name under kernels 1.3.9 and newer. On older kernels, the 
Linux implementation will allow the receipt of any signal, not just the one you are installing (effectively overriding any 
sa_mask settings). 

ThesA_RESETHAND and sa_nodefer namesforSVR4 compatibility are present only in library versions 3.0.9 and greater. 

sigaction can be called with a null second argument to query the current signal handler. It can also be used to check whether 
a given signal is valid for the current machine by calling it with null second and third arguments. 

See sigsetops(3) for details on manipulating signal sets. 

C0NF0RMST0 

POSIX, SVR4 

SEE ALSO 

kill(l), kill(2), killpg(2), pause(2), raise(3), sigintemjpt(3), signal(2), signal(7), sigse-tops(3), sigvec(2) 

Linux 1.3, 24 August 1995 
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signal— AN SI C signal handling 

SYNOPSIS 

#include <signal.h> 

void (*signal(int si gnum,void (*handI er )(int)))(int); 

DESCRIPTION 

The signal system call installs a new signal handler for the signal with number si gnum. The signal handler is set to handi er, 
which can be a user-specified function or one of the following: 

sig_ign Ignores the signal. 

sig_dfl Resets the signal to its default behavior. 

The integer argument that is handed over to the signal-handling routine is the signal number. This makes it possible to use 
onesignal handler for several signals. 

RETURN VALUE 

signal returns the previous value of the signal handler, or sig_err on error. 

NOTES 

Signal handlers cannot be set for sigkill or sigstop. 

Unlike on BSD systems, signals under Linux are reset to their default behavior when raised. However, if you include <bsd/ 
signal. h> instead of <signai.h>, signal is redefined as _bsd_signai, and signal has the BSD semantics. Both versions of 
signal are library routines built on top of sigaction(2). 

If you're confused by the prototype at the top of this man page, it may help to see it separated out I ike this: 

typedef void (*sighandler_t)(int); 

sighandler_t signal(int si gnum, sighandler_t handler); 

According to POSIX, the behavior of a process is undefined after it ignores a sigfpe, sigill, or sigsegv signal that was not 
generated by the km o or raise o function. Integer division by 0 has undefined result. 0 n some architectures it will 
generate a sigfpe signal. Ignoringthissignal might lead to an endless loop. 
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CONFORMSTO 

ansi c 

SEE ALSO 

kill(l), kill(2), killpg(2), pause(2), naise(3), sigaction(2), signal(7), sigsetops(3), sigvec(2), alarm(2) 

Linux2.0, 21 July 1996 

sigblock, siggetmask,sigsetmask,sigmask 

sigblock, siggetmask, sigsetmask, sigmask — M anipulate the signal mask 

SYNOPSIS 

#include <signal.h> 
int sigblock(int mask); 
int siggetmask(void); 
int sigsetmask(int mask); 
int sigmask(int signum); 

DESCRIPTION 

T his interface is made obsolete by sigprocmask(2). 

T he sigblock system call adds the signals specified in mask to the set of signals currently being blocked from delivery. 

The sigsetmask system call replaces the set of blocked signals totally with a new set specified in mask. Signals are blocked if 
thecorrespondingbitin mask isal. 

T he current set of blocked signals can be obtained using siggetmask. 

Thesigmask macro isprovided to construct the mask for a given si g num. 

RETURN VALUES 

siggetmask returns the current set of masked signals, 
sigsetmask and sigblock return the previous set of masked signals. 

NOTES 

Prototypes for these functions are only available if _use_bsd is defined before <signai.h> is included. 

It is not possible to block sigkill or sigstop— this restriction is silently imposed by the system. 

HISTORY 

These function callsappeared in BSD 4.3 and are deprecated. 

SEE ALSO 

kill(2), sigprocmask(2), signal(7) 

Linux 1.3, 31 August 1995 

sigpause 

sigpause— Atomically releases blocked signals and waits for interrupt 
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SYNOPSIS 

#include <signal.h> 
int sigpause(int sigmask); 

DESCRIPTION 

T his interface is made obsolete by sigsuspend(2). 

sigpause assigns si g ma s k to the set of masked signals and then waits for a signal to arrive; on return, the set of masked signals 
is restored. 

sigmask is usually 0 to indicate that no signals are to be blocked, sigpause always terminates by being interrupted, returning 

-1 with errno Set tO EINTR. 

HISTORY 

T he sigpause function call appeared in BSD 4.3 and isdeprecated. 

SEE ALSO 

sigsuspend(2), kill(2), sigaction(2), sigprocmask(2), sigblock(2), sigvec(2) 

Linux 1.3, 24July 1993 
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sigreturn— Returns from the signal handler and cleans up the stack frame 

SYNOPSIS 

int sigreturn(unsigned long _unused); 

DESCRIPTION 

WhentheLinux kernel creates the stack frame for a signal handler, acall to sigreturn is inserted into the stack frame so that 
the signal handler will call sigreturn upon return. This inserted call to sigreturn cleans up the stack so that the process can 
restart from where it was interrupted by the signal. 

RETURN VALUE 

sigreturn never returns 

WARNING 

The sigreturn call is used by the kernel to implement signal handlers. It should never be called directly. Better yet, the 
specific use of the unused argument varies depending on the architecture. 

C0NF0RMST0 

sigreturn is specific to Linux. 

FILES 

/usr/src/linux/arch/i386/kernel/signal.c 
/usr/src/linux/arch/alpha/kernel/entry.S 

SEE ALSO 

kill(2), signal(2), signal(7) 


Linux 1.3.20, 21 August 1995 
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sigvec 

sigvec— BSD software signal facilities 

SYNOPSIS 

#include <bsd/signal.h> 

int sigvec(int sig, struct sigvec *vec , struct sigvec *ovec); 

DESCRIPTION 

This interface is made obsolete by sigaction(2). 

Under Linux, sigvec is#defined to sigaction, and provides at best a rough approximation of the BSD sigvec interface. 

SEE ALSO 

sigaction(2), signal(2) 

Linux 1.3 31 August 1995 

socket 

socket— C reates an endpoint for communication 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/socket.h> 

int socket(int domai n , intt y pe , int protocol ); 

DESCRIPTION 

socket creates an endpoint for communication and returns a descriptor. 

The domai n parameter specifies a communications domain within which communication will take place; this selects the 
protocol family that should be used. These families are defined in the include file sys/socket. h. The currently understood 
formats are 

afjjnix UNIX internal protocols 

af_inet ARPA Internet protocols 

af_iso ISO protocols 

af_ns X erox N etwork Systems protocols 

af implink IM P host at IM P link layer 

The socket has the indicated type, which specifies the semantics of communication. The currently defined types are 

SOCK_STREAM 

SOCK_DGRAM 

SOCK_RAW 

SOCK_SEQPACKET 

SOCK_RDM 

A sock_stream type provides sequenced, reliable, two-way connection-based byte streams. An out-of-band data transmission 
mechanism may be supported. A sock_dgram socket supports datagrams (connectionless, unreliable messages of a fixed, 
typically small, maximum length). A sock_seqpacket socket may provide a sequenced, reliable, two-way connection-based 
data transmission path for datagrams of fixed maximum length; a consumer might be required to read an entire packet with 
each read system call. This facility is protocol specific, and presently isimplemented only for pf_ns. sock_raw sockets provide 
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access to internal network protocols and interfaces. The types sock_raw, which is available only to the superuser, and 
sock_rdm, which is planned but not yet implemented, are not described here. 

The protocol specifies a particular protocol to be used with the socket. N ormally only a single protocol exists to support a 
particular socket type within a given protocol family. H owever, it is possible that many protocols may exist, in which case a 
particular protocol must be specified in this manner. The protocol number to use is particular to the communication domain 
in which communication isto take pi ace; seeprotocois(5). 

Sockets of type sock_stream are full-duplex byte streams, similar to pipes. A stream socket must be in a connected state before 
any data can be sent or received on it. A connection to another socket is created with a connect(2) call. Once connected, data 
may be transferred using read(2) and write(2) calls or some variant of thesend(2) and recv(2) calls. W hen a session has been 
completed, aciose(2) may be performed. Out-of-band data can also be transmitted as described in send(2) and received as 
described in recv(2). 

The communications protocols used to implement a sock_stream ensure that data is not lost or duplicated. If a piece of data 
for which the peer protocol has buffer space cannot be successfully transmitted within a reasonable length of time the 
connection is considered broken, and calls will indicate an errorwith -i returns and with etimedout as thespecific codein the 
global variable emno. The protocolsoptionally keep sockets warm by forcing transmissions roughly every minute in the 
absence of other activity. An error is then indicated if no response can be elicited on an otherwise idle connection fora 
extended period (for example, 5 minutes). A sigpipe signal is raised if a process sends on a broken stream; thiscauses naive 
processes, which do not handle the signal, to exit. 

sock_seqpacket sockets employ the same system calls as sock_stream sockets. The only difference is that read(2) calls will 
return only the amount of data requested, and any that is remaining in the arriving packet will be discarded. 

sock_dgram and sock_raw sockets allow the sending of datagrams to correspondents named in send(2) calls. Datagrams are 
generally received with recvfrom(2), which returns the next datagram with its return address. 

An fcnti(2) call can be used to specify a process group to receive a sigurg signal when the out-of-band data arrives. It can 
also enable non-blocking I/O and asynchronous notification of I/O events via sigio. 

The operation of sockets is controlled by socket-level options. These options are defined in the file sys/socket. h. 
setsockopt(2) and getsockopt(2) and are used to set and get options respectively. 

RETURN VALUES 

A -i is returned if an error occurs; otherwise, the return value is a descriptor referencing the socket. 

ERRORS 

EPROTONOSUPPORT 
EMFILE 
ENFILE 
EACCESS 
ENOBUFS 

HISTORY 

The socket function call appeared in BSD 4.2. 

SEE ALSO 

accept(2), bind(2), cannect(2), getprotaent(3), getsackname(2), getsockopt(2), ioctl(2), listen(2), read(2), recv(2), 
select(2), send(2), shutdown(2), socketpair(2), write(2) 

"An Introductory 4.3 BSD Interprocess Communication Tutorial’' is reprinted in UNIX Programmer's Supplementary 
DocumentsVolumel 

"BSD Interprocess Com muni cation T utorial" is reprinted in U NIX Programmer's Supplementary DocumentsVolumel 

BSD Man Page 24July 1993 


Theprotocol type or thespecified protocol is not supported within thisdomain. 

T he per-process descri ptor table is full. 

The system file table is full. 

Permission to create a socket of thespecified type and/or protocol is denied. 

Insufficient buffer space is available. The socket cannot be created until sufficient resources are 
freed. 
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socketcall 

socketcaii— Socket system calls 

SYNOPSIS 

int socketcall(int call , unsigned long *args); 

DESCRIPTION 

socketcaii is a common kernel entry point for the socket system calls call determines which socket function to invoke, ar gs 
points to a block containing the actual arguments, which are passed through to the appropriate call. 

User programs should call the appropriate functions by their usual names. 0 nly standard library implementors and kernel 
hackers need to know about socketcaii. 

SEE ALSO 

accept(2), bind(2), connect(2), getpeername(2), getsockname(2), getsockopt(2), listen(2), recv(2), recvfrom(2), send(2), 
sendto(2), setsockopt(2), shutdown(2), socket(2), socketpair(2) 

Linux 1.2.4,15 April 1995 


socketpair 

socketpair— C reates a pair of connected sockets 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/socket.h> 

int socketpair(int d, int type, int protocol , int sv[2]); 

DESCRIPTION 

The call creates an unnamed pair of connected sockets in the specified domain d, of the specified type, and using the 
optionally specified protocol .The descriptors used in referencing the new sockets are returned in sv [ 0 ] and sv[i]. The two 
sockets are indistinguishable. 

RETURN VALUE 

O n success, 0 is returned. 0 n error, -1 is returned, and errno isset appropriately. 

ERRORS 

EMFILE 

EAFNOSUPPORT 
EPROTONOSUPPORT 
EOPNOSUPPORT 
EFAULT 

HISTORY 

The socketpair function call appeared in BSD 4.2. 

BUGS 

Thiscall is currently implemented only for theU N IX domain. 


T oo many descriptors are in use by this process. 

The specified address family is not supported on this machine. 

The specified protocol is not supported on this machine. 

The specified protocol does not support creation of socket pairs 
T he address s * does not specify a vali d part of the process's address space. 



stat, fiat, Istat 



SEE ALSO 

read(2), write(2), pipe(2) 
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stat,fstat,Istat 

stat, tstat, istat— Get file status 

SYNOPSIS 

#include <sys/stat.h> 

#include <unistd.h> 

int stat(const char *f i I e_name ,struct stat *buf); 

int fstat(int f i I edes ,struct stat *buf); 

int Istat (const char filename, struct stat *buf); 

DESCRIPTION 

These functions return information about the specified file. You do not need any access rights to the file to get this 
information, but you need search rights to all directories named in the path leading to the file. 

stat stats the file pointed to by f i i e_name and fills in but. 

istat is identical to stat, except that the link itself is stated, not the file that is obtained by tracing the links. 

tstat is identical to stat, except that the open file pointed to by f i i edes (as returned by open(2)) is stated in place of 

f i I e _ n a me. 

T hey all return a stat structure, which is declared as follows: 

struct stat 
{ 


dev_t 


st dev; 

/* 

device */ 

ino_t 


st _i no; 

/* 

inode */ 

umode_t 


s t _ mo d e; 

/* 

orotection */ 

nlink_t 


st_nl i nk; 

/* 

number of hard links */ 

uid_t 


st _uid; 

/* 

user ID of owner */ 

gid_t 


st _gi d; 

/* 

group ID of owner */ 

dev_t 


st_rdev; 

/* 

device type (if inode device) 

off_t 


st _si ze; 

/* 

total size, in bytes */ 

unsigned 

long 

st_b1 ksize; 

/* 

blocksize for filesystem I/O 

unsigned 

long 

st _bl ocks ; 

/* 

number of blocks allocated */ 

time_t 


s t _ a t i me; 

/* 

time of last access */ 

time_t 


s t _ mt i me; 

/* 

time of last modification */ 

time_t 


s t _ c t i me; 

/* 

time of last change */ 


}; 

N ote that st _b i neks may not always be in terms of blocks of sizes t_b ksiie, and that st_bi ksi ze may instead provide a 
notion of the "preferred" block sizefor efficient filesystem I/O. 

N ot all the Linux filesystems implement all the time fields. T raditionally, st.ati me is changed by mknod(2), utime(2), read(2), 
write(2), and truncate(2). 

T raditionally, st.mti me is changed bymknod(2), utime(2), andwrite(2). st.mti me is not changed for changes in owner, group, 
hard link count, or mode. 

T raditionally, st.ctl me is changed by writing or by setting inode information (that is, owner, group, link count, mode, and 
so on). 
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T he followi ng macros are defined to check thefiletype: 


S_ISLNK(m) 

SISREG(m) 

S_I SDIR (m) 

S_ISCHR(m) 

S_ISBLK(m) 

S_ISFIFO(m) 

S_ISSOCK(m) 


Is it a symbolic link? 
Isit a regular file? 

Is it a directory? 

Is it a character device? 
Is it a block device? 
Isitfifo? 

Is it a socket? 


T hefollowing flags are defined for the st _ mode field: 


S_IFMT 

S_IFSOCK 

S_IFLNK 

S_IFREG 

S_IFBLK 

S_IFDIR 

S_IFCHR 

S_IFIF0 

S_ISUID 

S_ISGID 

S_ISVTX 

S_IRWXU 

S_IRUSR (S_IREAD) 

S_IWUSR (s_iwrite) 

S_IXUSR (s_iexec) 

S_IRWXG 

S_IRGRP 

S_IWGRP 

S_IXGRP 

S_IRWXO 

S_IR0TH 

S_IW0TH 

S_IXOTH 


00170000 Bitmask for thefiletype bitfields 

0140000 Socket 

0120000 Symbolic link 

0100000 Regular file 

0060000 Block device 

0040000 D irectory 

0020000 C haracter device 

0010000 Fifo 

0004000 Set UID bit 

0002000 Set GID bit 

0001000 Sticky bit 

00700 User (fileowner) has read, write, and execute permission 

00400 U ser has read permission 

00200 User has write permission 

00100 User has execute permission 

00070 G roup has read, write, and execute permission 

00040 Group has read permission 

00020 Group has write permission 

00010 G roup has execute permission 

00007 others have read, write, and execute permission 

00004 Others have read permission 

00002 Others have write permission 

00001 Others have execute permission 


RETURN VALUE 

On success, 0 is returned. On error, -1 isreturned, and errno is set appropriately. 


ERRORS 

EBADF f i I edes is bad. 

enoent Filedoes not exist. 


C0NF0RMST0 

SVID (not istato), AT&T (not istat ()), POSIX (not istat ()), X/OPEN (not istato), BSD 4.3 

SEE ALSO 

chmod(2), chown(2), readlink(2), utime(2) 


Linux 1.1.75,1 January 1995 
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statfs,fstatfs 

statts, fstatfs— Get filesystem statistics 

SYNOPSIS 

#include <sys/vfs.h> 

int statfs(const char *pat h, struct statfs *buf); 
int fstatfs(int fd, struct statfs *buf); 

DESCRIPTION 

statfs returns information about a mounted filesystem, path is the pathname of any file within the mounted filesystem, but 
isapointerto a statfs structure defined as follows: 

struct statfs { 


long 

f_type; 

/* type of filesystem (see below) */ 

long 

f_bsize; 

/* optimal transfer block size */ 

long 

f_blocks; 

/* total data blocks in filesystem */ 

long 

f_bfree; 

/* free blocks in fs */ 

long 

f_bavail; 

/* free blocks avail to non-superuser 

long 

f_files; 

/* total file nodes in filesystem */ 

long 

f_ffree; 

/* free file nodes in fs */ 

fsid_t 

f_fsid; 

/* filesystem id */ 

long 

f_namelen; 

/* maximum length of filenames */ 

long 

f_spare[6]; 

/* spare for later */ 


}; 


Filesystem types: 


linux/ext2_fs.h: 

EXT2_0 L D_S U P E R_MAGIC 

0XEF51 


linux/ext2_fs.h: 

EXT2_SUPER_MAGIC 

0XEF53 


linux/ext_fs.h: 

EXT_SUPER_MAGIC 

0X137D 


linux/iso_fs.h: 

ISOFS_SUPER_MAGIC 

0x9660 


linux/minix_fs.h: 

MINIX_SUPER_MAGIC 

0X137F /* 

orig. minix * 

linux/minix_fs.h: 

MINIX_SUPER_MAGIC2 

0X138F /* 

30 char minix 

linux/minix_fs.h: 

NEW_MINIX_SUPER_MAGIC 

0x2468 /* 

minix V2 */ 

linux/msdos_fs.h: 

MSDOS_SUPER_MAGIC 

0x4d44 


linux/nfs_fs.h: 

NFS_SUPER_MAGIC 

0x6969 


linux/proc_fs.h: 

PROC_SUPER_MAGIC 

0x9fa0 


linux/xia_fs.h: 

XIAFS_SUPER_MAGIC 

0X012FD16D 


Fields that are undefined for a particular filesystem are set to -i. fstatfs returns the same information about an open file 
referenced by descriptor f d. 

RETURN VALUE 

On success, 0 is returned. On error, -1 isreturned, and errno is set appropriately. 

ERRORS 

For staffs: 

ENOTDIR 
EINVAL 

ENAMETOOLONG 

ENOENT 
EACCES 
ELOOP 


A component of the path prefix of path is not a directory, 
path contains a character with the high-order bit set. 

The length of a component of path exceeds 255 characters, or the length of path exceeds 1,023 
characters. 

The file referred to bypath does not exist. 

Search permission is denied for a component of the path prefix of pat h. 

T oo many symbolic I inks were encountered in translating path. 
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EFAULT 
EIO 

For fstatfs: 

EBADF 
EFAULT 
EIO 

SEE ALSO 

stat(2) 

stime 

stime — Set time 

SYNOPSIS 

#include <time.h> 
int stime (time_t *t ); 

DESCRIPTION 

stime sets the system's idea of the time and date, time, pointed to byt, is measured in seconds from 00:00:00 GMT January 
1,1970. stimeo may only be executed by the superuser. 

RETURN VALUE 

On success, 0 isreturned. On error, -1 isreturned, and errno is set appropriately. 

ERRORS 

eperm The caller is not the superuser. 

C0NF0RMST0 

SVID, AT&T, X/OPEN 

SEE ALSO 

date(l) 

Linux0.99.11, 24July 1993 


buf or path points to an invalid address. 

An I/O error occurred while reading from or writing to the filesystem. 

fd is not a valid open file descriptor, 
hut points to an invalid address. 

An I/O error occurred while reading from or writing to the filesystem. 


Linux0.99.11, 24July 1993 


swapon, swapoff 

swapon, swapoff— Start/stop swapping to fil^device 

SYNOPSIS 

#include <unistd.h> 

#include <linux/swap.h> 

int swapon(const char *path, int swapflags); 

int swapoff(const char *path); 



s/mlink 

DESCRIPTION 

swapon sets the swap area to the file or block device specified by path, swapoft stops swapping to the file or block device 
specified bypath. 

swapon takes a swapf i ags argument. If swapf i ags has theswAP_FLAG_PREFER bit turned on, the new swap area will have a higher 
priority than default. The priority is encoded as (prio « swap_flag_prio_shift) & swap_flag_prio_mask. These functions 
may only be used by the superuser. 

PRIORITY 

Each swap area has a priority, either high or low. The default priority is low. Within the low-priority areas, newer areas are of 
even lower priority than older areas. 

All priorities set with swapf i ags are high priority, higher than the default. They may have any non-negative value chosen by 
the caller. H igher numbers mean higher priority. 

Swap pages are allocated from areas in priority order, highest priority first. For areas with different priorities, a higher- 
priority area is exhausted before using a lower-priority area. If two or more areas have the same priority, and that is the 
highest priority available, pages are allocated on a round-robin basis between them. 

As of Linux 1.3.6, the kernel usually follows these rules, but there are exceptions. 

RETURN VALUE 

On success, 0 isreturned. On error, -1 isreturned, and errno is set appropriately. 

ERRORS 

M any other errors besides the following can occur if path isnot valid: 

eperm The user isnot the superuser, or more than max_swapfiles (defined to be 8 in Linux 1.3.6) are in 

use. 

einval Returned if path exists, but is neither a regular path nor a block device. 

enoent Returned if path does not exist. 

enohem Returned if there is insufficient memory to start swapping. 

C0NF0RMST0 

T hesefunctions are Linux specific. 

NOTES 

The partition or path must be prepared with mkswap(8). 

HISTORY 

Thesecond (swaptiags) argument was introduced in Linux 1.3.2. 

SEE ALSO 

mkswap(8), swapon(8), swapoff(8) 

Linux 1.3.6, 22 July 1995 

symlink 

symiink — M akes a new nameforafile 
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SYNOPSIS 

#include <unistd.h> 

int symlink(const char *oI dpat h, const char *newpat h); 

DESCRIPTION 

symiink creates a symbolic link named oi dpat h that contains newpat h. 

Symbolic links are interpreted at runtime, as if the contents of the link were substituted into the path being followed to find 
a file or directory. 

Symbolic linksmay contain .. path components that (if used at the start of the link) refer to the parent directories of the one 
in which the link resides. 

A symbolic link (also known as a soft link) can point to an existing file or to a nonexistent one; the latter case is known as a 
dangling link. 

The permissions of a symbolic link are irrelevant; the ownership is ignored when following the link, but is checked when 
removal or renaming of the link is requested and thelink isin a directory with the sti cky bit set. 

If newpat h exists, it will not be overwritten. 

RETURN VALUE 

0 n success, 0 is returned. 0 n error, -1 is returned, and errno isset appropriately. 

ERRORS 

EPERM 
EFAULT 
EACCES 

ENAMETOOLONG 
ENOENT 

ENOTDIR 
ENOMEM 
EROFS 
EEXIST 
ELOOP 

ENOSPC 

NOTES 

N 0 checkingof oidpath isdone. 

Deleting the name ref erred to by a symiink will actually delete thefile (unless it also has other hard links). If this behavior is 
not desired, use link. 

C0NF0RMST0 

SVID, AT&T, POSIX, BSD 4.3 

BUGS 

Seeopen(2) regardingmultiplefileswith thesamename, and N FS. 


The filesystem containing pathname does not support the creation of symbolic links, 
oi dpath or newpat h points outside your accessible address space. 

Write access to the directory containing newpat h is not allowed for the process's effective U I D, or 
oneof the directories in newpat h did not allow search (execute) permission. 

ol dpat h Or newpat h W3S tOO long. 

A directory component in newpat h does not exist or is a dangling symbolic link, or oi dpath is the 
empty string. 

A component used as a directory in newpat h isnot, in fact, a directory. 
Insufficientkernelmemorywasavailable. 

Thefileison a read-only filesystem, 
newpat h already exists. 

newpat h contains a reference to a circular symbolic link— that is, a symbolic link whose expansion 
containsa reference to itself. 

T he device containing the fi le has no room for the new directory entry. 
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SEE ALSO 

link(2), unlink(2), rename(2), open(2), 1stat(2), ln( 1), link(8) 


Linux, 24 July 1993 


sync 

sync— Commits buffer cache to disk 

SYNOPSIS 

#include <unistd.h> 
int sync(void); 

DESCRIPTION 

sync first commits inodes to buffers, and then buffers to disk. 

RETURN VALUE 

sync always returns 0 . 

C0NF0RMST0 

SVID, AT&T, X/O PEN , BSD 4.3 

BUGS 

According to the standard specification (for example, SVID), synco schedules the writes, but it might return before the 
actual writing is done. However, since version 1.3.20, Linux does actually wait. (T his sti II does not guarantee data integrity; 
modern disks have large caches.) 

SEE ALSO 

bdflush(2), fsync(2), fdatasync(2), update(8), sync(8) 

Linux 1.3.88,15 April 1995 


sysctl 

syscti— Read^writes system parameters 

SYNOPSIS 

#include <unistd.h> 

#include <linux/unistd.h> 

#include <linux/sysctl.h> 

_syscall1(int_sysct I , struct _sysctl_args *args); 

int sysctl(struct _sysctl_args *args); 

DESCRIPTION 

The syscti call reads and/or writes kernel parameters—for example, the hostname or the maxi mum number of open files. 
The argument has the form 
struct _sysctl_args { 

int *name; /* integer vector describing variable */ 
int nlen; /* length of this vector */ 
void *oldval; /* 0 or address where to store old value */ 
size_t *oldlenp; /* available room for old value, 
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overwritten by actual size of old value */ 
void *newval; /* 0 or address of new value */ 
size_t newlen; /* size of new value */ 

}; 

This call does a search in a tree structure possibly resembling a directory tree under /proc/sys, and, if the requested item is 
found, cal Is some appropriate routine to read or modify the value. 

EXAMPLE 

#include <linux/unistd.h> 

#include <linux/types.h> 

#include <linux/sysctl.h> 

_syscall1(int, _sysctl, struct _sysctl args *, args); 

int sysctl(int *name, int nlen, void *oldval, size_t *oldlenp, 
void *newval, size_t newlen) 

{ 

struct _sysctl_args args={name,nlen,oldval,oldlenp,newval,newlen}; 

return _sysctl(&args); 

} 

#define SIZE(x) sizeof(x)/sizeof(x[0]) 

#define OSNAMESZ 100 

char osname[OSNAMESZ]; 
int osnamelth; 

int name[] = { CTL_KERN, KERN_OSTYPE }; 
main(){ 

osnamelth = SIZE(osname); 

if (sysctl(name, SIZE(name), osname, &osnamelth, 0, 0)) 
perror("sysctl"); 

else 

printf("This machine is running %*s\n", osnamelth, osname); 
return 0; 

} 

RETURN VALUES 

Upon successful completion, sysctl returns 0 . Otherwise, a value of -1 is returned, and errno is set to indicate the error. 

ERRORS 

ENOTDIR name was not found. 

eperm N 0 search permission for one of the encountered directories, or no read permission where 0 dva 1 

was nonzero, or no write permission wherenewvai was nonzero. 
efault The invocation asked for the previous value by setting oi dva 1 non-N U LL, but allowed zero room 

in ol dl enp. 

C0NF0RMST0 

Thiscall is Linux specific. 

HISTORY 

A sysctl call has been present in Linux si nee version 1.3.57. It originated in BSD-4.4. 0 nly Linux hasthe/proc/sys mirror, 
and the object-naming schemes differ between Linux and BSD 4.4, but the declaration of the syscti(2) function isthesame 
in both. 
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BUGS 

N ot all available objects are properly documented. 

It is not yet possible to change operating system by writing to /proc/sys/kernei/ostype. 

SEE ALSO 

proc(5) 

Linux 1.3.85,11 April 1996 

sysfs 

sysfs— Gets filesystem type information 

SYNOPSIS 

int sysfs(int option, const char * fsname); 

int sysfs(int opti on , unsigned int f s _i ndex , char * buf ) ; 

int sysfs(int option); 

DESCRIPTION 

sysfs returns information about the filesystem types currently present in the kernel. The specific form of the sysfs call and 
the information returned depend on theoption in effect. You can 

■ Translate the filesystem identifier string f sname into a filesystem type index. 

■ T ranslate the filesystem type index fs j ndex into a null-terminated filesystem identifier string. This string will be written 
to the buffer pointed to by buf. M ake sure that buf has enough space to accept the string. 

■ Return the total number of filesystem types currently present in the kernel. 

The numbering of thefi lesystem type indexes begins with 0. 

RETURN VALUE 

On success, sysfs returns thefi lesystem index for the first option, a for the second option, and the number of currently 
configured filesystems for the third option. On error, -i is returned, and errno is set appropriately. 

ERRORS 

einval fsname is not a valid filesystem type identifier; f s_i ndex is out of bounds; option isinvalid. 

efault Either f sname or b u f is outside your accessible address space. 

C0NF0RMST0 

System V 

Linuxl.3.16, 9Augustl995 

sysinfo 

sysinfo— Returns information on overall system statistics 

SYNOPSIS 

As of Linux 0.99.10 and image release 4.4, 

#include <linux/kernel.h> 

#include <linux/sys.h> 

int sysinfo(struct sysinfo *info); 
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DESCRIPTION 

sysinfo returns information in the following structure: 
struct sysinfo { 

long uptime; /* Seconds since boot */ 

unsigned long loads[3]; /* 1, 5, and 15 minute load averages */ 

unsigned long totalram; /* Total usable main memory size */ 

unsigned long freeram; /* Available memory size */ 

unsigned long sharedram; /* Amount of shared memory */ 

unsigned long bufferram; /* Memory used by buffers */ 

unsigned long totalswap; /* Total swap space size */ 

unsigned long freeswap; /* swap space still available */ 

unsigned short procs; /* Number of current processes */ 

char _f[22]; /* Pads structure to 64 bytes */ 

}; 

sysinfo provides a simple way of getting overall system statistics. T his is more portablethan reading /dev/kmem. 

RETURN VALUE 

O n success, 0 is returned. 0 n error, -1 is returned, and errno isset appropriately. 

ERRORS 

efault The pointer to struct sysinfo is invalid. 

C0NF0RMST0 

T his function is Linux specific. 

BUGS 

T he Linux D LL 4.4.1 libraries do not contain a proper prototype for this function. 

Linux0.99.10, 24July 1993 

syslog 

sysiog— Reads and/or clears kernel message ring buffer; setsconsoie_iogievei 

SYNOPSIS 

#include <unistd.h> 

#include <linux/unistd.h> 

_syscall3(int syslog, int type, char *b u f p, int len); 
int syslog(int type, char *bufp, int len); 

DESCRIPTION 

This is probably not the function you are interested in. Look atsysiog(3) for the C library interface. This page only 
documents the bare kernel system call interface. 

Thetype argument determines the action taken by syslog. 

From kernel/printk.c:/* 

Valid commands to syslog are 
0 — C losethe log. Currently a NOP. 

1 — Open the log. Currently a NOP. 

2 — Read from the log. 
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3— Read up to the last 4K B of messages in the ring buffer. 

4— Read and clear last 4KB of messages in the ring buffer. 

5— Clear ring buffer. 

6— D isableprintksto console 

7 — Enable printksto console. 

8— Set level of messages printed to console. 

Only function 3 is allowed to non-root processes. 

THE KERN EL LOG BUFFER 

T he kernel has a cyclic buffer of length log_buf_len (4096) in which messages given as argument to the kernel function 
printk () are stored (regardless of their loglevel). 

The call sysiog (2,buf ,i en) waits until this kernel log buffer is nonempty, and then reads at mosti en bytes into the buffer 
buf . It returns the number of bytes read. Bytes read from the log disappear from the log buffer; the information can only be 
read once. This is the function executed by the kernel when a user program reads /proc/kmsg. 

The call sysiog ( 3 ,buf Jen) will read the last i en bytes from the log buffer (nondestructively), but will not read more than 
was written into the buffer si nee the last "clear ring buffer” command (which does not clear the buffer at all). It returns the 
number of bytes read. 

Thecall sysiog (4, buf ,i en ) does precisely the same, but also executes the "clear ring buffer" command. 

Thecall sysiog < 5 , dummy ,i dummy) only executes the "dear ring buffer" command. 

THE LOG LEVEL 

Thekernel routine printko will print a messageon the console only if it hasa loglevel less than the value of the variable 
consol e_i ogi evei (initially DEFAULT_coNsoLE_i_oGLEVEL (7), but set to 10 if the kernel command line contains the word debug, 
and to 15 in case of a kernel fault—the 10 and 15 are just silly, and are equivalent to 8). This variable is set (to a value in the 
range 1-8) by the call sysiog (8, dummy ,vai ue ). T he call sysiog (type, dummy ,i dummy ) with type equal to 6 or 7, sets it to 1 
(kernel panicsonly) or 7 (all except debugging messages), respectively. 

Every text line in a message has its own loglevel. This level Isdefault_message_loglevel-i (6) unless the line starts with <d> 
where d is a digit in the range 1-7, in which case the level isd. The conventional meaning of the loglevel is defined in <iinux/ 
kernel.h> 3S follows: 


#define 

KERN_ 

EMERG 

11 < 0> 11 

/* 

system is unusable 

1c 

#define 

KERN_ 

ALERT 

11 < 1 > 11 

/* 

action must be taken immediately 

* 

#define 

KERN_ 

CRIT 

"<2>" 

/* 

critical conditions 

★ 

#define 

KERN_ 

ERR 

■ <3 > 11 

/* 

error conditions 

* 

#define 

KERN_ 

WARNING 

"<4>" 

/* 

warning conditions 

* 

#define 

KERN_ 

NOTICE 

"<5>" 

/* 

normal but significant condition 

* 

#define 

KERN_ 

INFO 

"<6>" 

/* 

informational 

* 

#define 

KERN_ 

DEBUG 

"<7>" 

/* 

debug-level messages 

* 


RETURN VALUE 

In case of error, -i isreturned, and errno is set. On success, for type equal to 2, 3, or 4, sysiogo returns the number of bytes 
read; otherwise it returns 0 . 

ERRORS 

eperm An attempt was madeto change consoie_iogievei or clear the kernel message ring buffer by a 

process without root permissions 
einval Bad parameters. 

System call was interrupted by a signal—nothing was read. 


ERESTARTSYS 
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CONFORMSTO 

Thissystem call is Linux specific. 

SEE ALSO 

syslog(3) 

Linux 1.2.9,11 Junel995 

termios, tcgetattr, tcsetattr, tcsendbreak,tcdrain,tcflush, 
tcflow, cfgetospeed, cfgetispeed, cfsetispeed,cfsetospeed, 
tcgetpgrp, tcsetpgrp 

termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow, cfgetospeed, cfgetispeed, cfsetispeed, cfsetospeed, 

tcgetpgrp, tcsetpgrp— Get and set terminal attributes, do line control, get and set baud rate, get and set terminal foreground 
process group ID 

SYNOPSIS 

#include <termios.h> 

#include <unistd.h> 

int tcgetattr ( int fd, struct termios *t e r mi o s _ p ); 

int tcsetattr ( int fd, int opt i onal act i ons , struct termios *t e r mi o s _ p ); 

int tcsendbreak ( int fd, int duration ); 

int tcdrain ( int f d ); 

int tcflush ( int fd, int queue_sel ector ); 

int tcflow ( int fd, int action ); 

speedjt cfgetospeed ( struct termios *termi os_p ); 

int cfsetospeed ( struct termios *t ermi os_p, speedjt speed ); 

speedjt cfgetispeed ( struct termios *ter mi os_p ); 

int cfsetispeed ( struct termios *t ermi os_p, speedjt speed ); 

pid_t tcgetpgrp ( int fd ); 

int tcsetpgrp ( int fd, pid_t pgr pi d ); 

DESCRIPTION 

The termios functions describe a general terminal interface that is provided to control asynchronous communications ports. 

M any of the functions described here have at er mi os_ p argument that is a pointer to a termios structure. This structure 
contains the following members: 

tcflag_t cj flag; /* input modes */ 
tcflag_t c_oflag; /* output modes */ 
tcflag_t c_cflag; /* control modes */ 
tcflag_t cjflag;/‘local modes*/ 
cc_t c_cc[ NCCS] ; /* control chars */ 

T he foil owing are the c j f i a g flag constants: 

ignbrk Ignore break condition on input. 

brkint If ignbrk isnot set, generate sigint on break condition; otherwise, read break as character\0. 

ignpar Ignore framing errors and parity errors. 

parmrk If ignpar isnot set, prefix a character with a parity error or framing error with \377 \0. If neither 

ignpar nor parmrk is set, read a character with a parity error or framing error as\0. 
inpck Enableinputparitychecking. 



termios, tcgetattr, tcsetattr, tcsndbreak, tcdrain, tcflush, tcflow, cfgetospeed, cfgetispeed, cf&ispeed, 

cf&oyeed, tcgetpg-p, tcsetpgrp 
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istrip Strip off the eighth bit. 

inlcr T ranslate N L to CR on input. 

igncr Ignore carriage return on input. 

icrnl T ranslate carriage return to newline on input (unless igncr is set). 

iuclc M ap uppercase characters to lowercase on input. 

ixon EnableXON/XOFF flow control on output. 

ixany E nable any character to restart output. 

ixoff EnableXON/XOFF flow control on input imaxbel ring bell when input queueisfull. 

T hefollowing are the c_of lag f I ag constants: 

opost Enableimplementation-defined output processing. 

olcuc M ap lowercase characters to uppercase on output. 

onlcr M ap N L to C R-N L on output. 

ocrnl M ap C R to N L on output. 

onocr D on't output CR at column 0. 

onlret D on't output C R. 

ofill Send fill characters for a delay rather than use a timed delay. 

ofdel Fill character isASC II DEL. If unset, fill character isASC 11 NUL. 

nldly N ewline delay mask. Values are nlb and nli. 

crdly Carriage-return delay mask. Values arecRo, cri, cr 2 , and cr3. 

tabdly H orizontal-tab delay mask. Values areTABo, tabi, tab 2 , tab3, and xtabs. A value of xtabs expands 

tabs to spaces (with tab stops every eight columns). 
bsdly Backspace delay mask. Values are bsb and bsi. 

vtdly Vertical-tab delay mask. Values are vto and vti. 

ffdly Form-feed delay mask. Values are ffo and ffi. 


T h e fo 11 owi n g are the c_cf lag f I ag con stants: 

csize C haracter size mask. Values arecss, cs6, csz.and css. 

cstopb Set two stop bits rather than one. 

cread Enable receiver. 

parenb Enable parity generation on output and parity checking for input. 

parodd Parity for input and output is odd. 

hupcl Lower modem control lines after last process closes the device (hangs up). 

ciocal Ignore modem control lines. 

cibaud Mask for input speeds (not used). 

crtscts Flow control. 


T hefollowing are the c_if lag f I ag con stants: 

isig When any of the characters intr, quit, susp, orDsusp are received, generate the corresponding 

signal. 

icanon Enables canonical mode. This allows the special characters eof, eol, eol 2 , erase, kill, reprint, 

status, and werase, and also buffers by lines. 

xcase If icanon isalso set, terminal is uppercase only. Input isconverted to lowercase, except for 

characters preceded by \. 0 n output, uppercase characters are preceded by \, and lowercase 
characters are converted to uppercase. 

echo Echo input characters. 
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echoe If icanon isalso set, the erase character erases the preceding input character, and werase erases the 

preceding word. 

echok If icanon isalso set, the kill character erases the current line 

echonl If icanon isalso set, echo theNL character even If echo is not set. 

echoctl If echo isalso set, ASCII control signals other than tab, nl, start, and stop are echoed asCtrl+X, 

where X is the character with ASCII code 0x10 greater than the control signal. For example, 
character 0x28 (BS) isechoed asCtrl +H . 

echoprt If icanon and iecho arealso set, characters are printed as they are being erased. 

echoke If icanon isalso set, kill isechoed by erasing each character on the line, as specified by echoe and 

echoprt. 

flusho Output is being flushed. Thisflag istoggled by typing the discard character. 

noflsh D isables flushing of the input and output queues when generating the sigint and sigquit signals, 

and flushing of the input queue when generating thesiGsusp signal. 
tostop Sends the sigttou signal to the process group of a background process that tries to write to its 

controlling terminal. 

pendin All characters in the input queue are reprinted when the next character is read, (bash handles 

typeahead thisway.) 

iexten Enable implementation-defined input processing. 

tcgetattro gets the parameters associated with the object referred by f d and stores them in thetermios structure referenced 
by ter mi os. p . T his function may be invoked from a background process; however, the terminal attributes may be subse¬ 
quently changed by a foreground process. 

tcsetattro sets the parameters associated with the terminal (unless support is required from the underlying hardware that is 
not available) from thetermios structure referred to by ter mi os.p. opt i onai _acti ons specifies when the changes take effect: 

tcsanow T he change occurs immediately. 

tcsadrain Thechangeoccursafterall output written to fd has been transmitted. Thisfunction should beused 

when changing parameters that affect output. 

tcsaflush Thechangeoccursafterall output written to the object referred to by f d has been transmitted, and 

all input that has been received but not read will be discarded before the change is made. 

tcsendbreako transmitsa continuous stream of zero-valued bits for a specific duration, if theterminal isusing asynchronous 
serial data transmission. If dur at i on is 0 , it transmits zero-valued bits for at least 0.25 seconds, and not more than 0.5 
seconds. If dur at i on is not 0 , it sends zero-valued bits for dur at i on *N seconds, where N is at least 0.25, and not more 
than 0.5. 

If theterminal is not using asynchronous serial data transmission, tcsendbreako returns without taking any action, 
tcdraino waits until all output written to the object referred to by f d has been transmitted. 

tctiusho discards data written to the object referred to by f d but not transmitted, or data received but not read, depending 
On the value Of queue.s el ec 1 0 r: 

tciflush Flushes data received but not read. 

tcoflush Flushes data written but not transmitted. 

tcioflush Flushes both data received but not read and data written but not transmitted. 

tctiowo suspends transmission or reception of data on the object referred to by f d, depending on the value of act i on: 

tcooff Suspends output. 

tcoon Restarts suspended output. 

tcioff T ransmitsa stop character, which stops the terminal device from transmitting data to thesystem. 

tcion T ransmitsa start character, which starts the terminal da/ice transmitting data to thesystem. 




termios, tcgetattr, tcsetattr, tcsndbreak, tcdrain, tcflush, tcflow, cfgetospeed, cfgetispeed, cf&ispeed, 

cf&oyeed, tcgetpgrp, tcsetpgrp 
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The default on open of a terminal file is that neither its input nor its output is suspended. 

The baud rate functions are provided for getting and setting the values of the input and output baud rates in the termios 
structure. The new values do not take effect until tcsetattr o is successfully called. 

Setti ng the speed to bo instructs the modem to hang up. The actual bit rate corresponding to B38400 may be altered with 

setserial(8). 

Theinput and output baud rates are stored in thetermios structure. 

cfgetospeed)) returns theoutput baud rate stored in thetermios structure pointed to by t e r mi os.p. 

cfsetospeedo sets the output baud rate stored in thetermios structure pointed to by ter mi os.p to speed, which must be one 
of these constants: 

B0 

B50 

B75 

B110 

B134 

B150 

B200 

B300 

B600 

B1200 

B1800 

B2400 

B4800 

B9600 

B19200 

B38400 

B57600 

B115200 

B230400 

The zero baud rate, B 0 , is used to terminate the connection. If b@ is specified, the modem control lines will no longer be 
asserted. N orm ally, this will disconnect the line cbaudex is a mask for the speeds beyond those defined in POSIX.1 (57600 
and later). Thus, B 57600 & cbaudex is nonzero. 

cfgetispeed)) returns the input baud rate stored in thetermios structure. 

cfsetispeed) ) sets theinput baud rate stored in thetermios structure to speed. Iftheinput baud rate i s set to 0 , it will be 
equal to theoutput baud rate. 

tcgetpgrpo returns the process group ID of the foreground processing group, or -1 on error. 

tcsetpgrpo sets the process group ID to pgrpid. pgrpid must bethelD of a process group in the same session. 

RETURN VALUES 

cfgetispeed)) returns the input baud rate stored in thetermios structure, 
cfgetospeed)) returns theoutput baud rate stored in thetermios structure, 
tcgetpgrpo returns the process group ID of foreground processing group, or -1 on error. 

All other functions return 
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0 0 n success. 

-i on failure (and set errno to indicate theerror). 


SEE ALSO 

setserial(8) 


Linux, 25 February 1995 


time 

time—Gets time in seconds 

SYNOPSIS 

#include <time.h> 
time_t time(time_t *t ); 

DESCRIPTION 

time returns the time since 00:00:00 GMT, January 1,1970, measured in seconds. 

If t is non null, the return value is also stored in the memory pointed to byt. 

C0NF0RMST0 

SVID, AT&T, POSIX, X/OPEN , BSD 4.3 

(UnderBSD 4.3, thiscall is made obsolete by gettimeotday(2).) 

SEE ALSO 

ctime(3), date(l), ftime(3), gettimeofday(2) 

Linux, 24July 1993 


times 

times—G ets process times 

SYNOPSIS 

#include <sys/times.h> 
clock_t times(struct tms *buf); 

DESCRIPTION 

times stores the current process times in but. 
struct tins isasdefined in /usr/include/sys/times.h: 
struct tms { 

time_t tms_utime; /* user time */ 
time_t tms_stime; /* system time */ 
time_t tms_cutime; /* user time of children */ 
time_t tms_cstime; /* system time of children */ 
}; 


times returns the number of clock ticks that have elapsed si nee the system has been up. 
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CONFORMSTO 

SVID, AT&T, POSIX, X/OPEN , BSD 4.3 

SEE ALSO 

time(l), getrusage(2), wait(2) 

Linux0.99.11, 24July 1993 


truncate,ftruncate 

truncate, ftruncate— T runcate a file to a specified length 

SYNOPSIS 

#include <unistd.h> 

int truncate(const char *p a t h , size_t length); 
int ftruncate(int fd, size_t length); 


DESCRIPTION 

truncate causes the file named bypath or referenced by f d to be truncated to at most i eng th bytes in size. If the file 
previously was larger than this size, the extra data is lost. W ith ftruncate, the file must be open for writing. 


RETURN VALUE 

On success, e is returned. On error, -i is returned, and errno isset appropriately. 


ERRORS 

The errors for truncate are 


ENOTDIR 

EINVAL 

ENAMETOOLONG 

ENOENT 

EACCES 

EACCES 

ELOOP 

EISDIR 

EROFS 

ETXTBSY 

EIO 

EFAULT 


A component of the path prefix is not a directory. 

T he pathname contains a character with the high-order bit set. 

A component of a pathname exceeded 255 characters, or an entire path name exceeded 1,023 
characters. 

T he named fi le does not exist. 

Search permission isdenied for a component of the path prefix. 

The named fi le is not writeable by the user. 

T oo many symbolic linkswere encountered in translating the pathname. 

Thenamed file isa directory. 

The named file resides on a read-only filesystem. 

T he file is a pure procedure (shared text) fi le that is being executed. 

An I/O error occurred updating the inode. 

path points outside the process's allocated address space. 


The errors for ftruncate are 
ebadf f d is not a valid descriptor. 

einval fd references a socket, not a file. 

einval f d is not open for writing. 


HISTORY 

These function callsappeared in BSD 4.2. 
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BUGS 

These calls should be generalized to allow ranges of bytes in a file to be discarded. 

SEE ALSO 

open(2) 

BSD Man Page 24July 1993 


umask 

umask— Sets a fi le-creation mask 

SYNOPSIS 

#include <sys/stat.h> 
int umask(int mask); 

DESCRIPTION 

umask sets the umask to mask 8,0777. 

RETURN VALUE 

T he previous value of the mask is returned. 

C0NF0RMST0 

SVID, AT&T, POSIX, X/OPEN , BSD 4.3 

SEE ALSO 

creat(2), open(2) 

Linux 24 July 93 


uname 

uname— Gets name and information about the current kernel 

SYNOPSIS 

#include <sys/utsname.h> 

int uname(struct utsname *buf); 

DESCRIPTION 

uname returns system information in buf.Theutsname struct is as defined in / usr/ include / sys / utsname. h: 

struct utsname { 

char sysname[65]; 
char nodename[65]; 
char release[65]; 
char version[65]; 
char machine[65]; 
char domainname[65]; 

}; 


RETURN VALUE 

O n success, e is returned. 0 n error, -i is returned, and errno isset appropriately. 



afs_s/s:all, break, gtty, lock, mpx, prof, quotactl, stty, ustat 
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ERRORS 

EFAULT buf isnot valid. 

C0NF0RMST0 

SVID, AT&T, POSIX, X/OPEN 

SEE ALSO 

uname(l), getdomainname(2), gethostname(2) 

Linux 0.99.11 24 July 93 


none 

none— U ndocumented system calls 

SYNOPSIS 

Undocumented system calls. 

DESCRIPTION 

As of Linux 1.3.88, there are 163 system calls listed in /usr/inciude/asm/unistd.h. This man page mentions those calls that 
are implemented in the kernel but not yet documented in man pages. Someof these calls do not yet have prototypes in the 
libc include files. 


SOLICITATION 

If you have information about these system calls, please look in the kernel source code, write a man page (using a style similar 
to that of the other Linux section 2 man pages), and send it to aeb@cwi.ni for inclusion in the next man page release from the 
Linux Documentation Project. 

STATUS 

Undocumented aremsync, readv, writev, getsid, fdatasync, sysctl, sched_setparam, sched_getparam, sched_setscheduler, 
sched_getscheduler, sched_yield, sched_get_priority_max, sched_get_priority_min l sched_rr_get_interval. 


SEE ALSO 

obsolete(2), unimplemented(2) 


Linux 1.3.86 12 April 1996 


at s_syscall, break, gtty, lock, mpx, prof, quotactl, stty, ustat 

afs_syscall, break, gtty, lock, mpx, prof, quotactl, stty, ustat —Unimplemented system calls 

SYNOPSIS 

Unimplemented system calls. 

DESCRIPTION 

These system calls are not implemented in the Linux 1.2.4 kernel. 

RETURN VALUE 

These system calls always return -i and set errno to enosys. 



Part II: System Calls 



SEE ALSO 

obsolete(2), undocumented^) 


Linux 1.2.4,15 April 1995 


unlink 

unlink— Deletes a name and possibly the file it refers to 

SYNOPSIS 

#include <unistd.h> 

int unlink(const char *pat hname); 

DESCRIPTION 

unlink deletes a name from the filesystem. If that name was the last link to a file and no processes have the file open, the file 
is deleted, and the space it was using is made available for reuse. 

If the name was the last link to a file but any processes still have the file open, the file will remain in existence until the last 
file descriptor referring to it is closed. 

If the name referred to a symbolic link, the link is removed. 

If the name referred to a socket, fifo, or device, the name for it is removed but processes that have the object open can 
continue to use it. 

RETURN VALUE 

O n success, 0 is returned. 0 n error, -1 is returned, and errno isset appropriately. 

ERRORS 

EFAULT 
EACCES 

EPERM 

ENAMETOOLONG 
ENOENT 
ENOTDIR 
EISDIR 
ENOMEM 
EROFS 

CON FORMS TO 

SVID, AT&T, POSIX, X/OPEN , BSD 4.3 

BUGS 

Infelicities in the protocol underlying N FS can cause the unexpected disappearance of files that are still being used. 

SEE ALSO 

link(2), rename(2), open(2), rmdir(2), mknod(2), mkfifo(3), remove(3), nm(l), unlink(8). 


p a t h n a me poi nts outsi de your accessi ble address space. 

W rite access to the di rectory containi ng pat hn a me is not allowed for the process's effecti ve UID, or 
one of the directories in pathname did not allow search (execute) permission. 

The directory containing pat hname has the sticky bit (s_isvtx) set, and the process's effective U ID is 
neither theU ID of thefileto be deleted nor that of the directory containing it, or pa t hn a me isa 
directory. 

pat hname wastOO long. 

A directory component in pat hname does not exist or isa dangling symbolic link. 

A component used as a directory in pathname is not, in fact, a directory, 
pathname refers to a directory. 

Insufficientkernelmemorywasavailable. 
pathname refers to a file on a read-only filesystem. 


Linux, 24July 1993 
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uselib 

useiib— Selects shared library 

SYNOPSIS 

#include <unistd.h> 

int uselib(const char *1i brary); 

DESCRIPTION 

useiib selects the shared library binary that will beused by this process. 

RETURN VALUE 

0 n success, 0 is returned. 0 n error, -1 is returned, and errno isset appropriately. 

ERRORS 

In addition to all the error codes returned by open(2) and mmap(2), the following may also be returned: 

enoexec The file specified by 1 i br a r y is not executable, or does not have the correct magic numbers. 

eacces Thelibrary specified by 1 i br a r y is not readable. 

C0NF0RMST0 

useiib () is Linux specific. 

SEE ALSO 

open(2), mmap(2), ldd(l), gcc( 1), ar(l), ld(l) 

Linux0.99.11, 24July 1993 


ustat 

ustat— Gets filesystem statistics 

SYNOPSIS 

#include <sys/types.h> 

int ustat(dev_t dev, struct ustat * ubuf); 

DESCRIPTION 

ustat returns information about a mounted filesystem, dev is a device number identifying a device containing a mounted 
filesystem, ubuf isa pointer to a ustat structure that contains the following members: 

daddr_t f_tfree; /* Total free blocks */ 
ino_t f_tinode; /* Number of free inodes */ 
char f_fname[6]; /* Filsys name */ 
char f_fpack[6]; /* Filsys pack name */ 

Thelasttwo fields, tjfname and t_fpack, arenot implemented and will always be filled with null characters. 

RETURN VALUE 

On success, 0 is returned, and the ustat structure pointed to by ubuf will be filled in. On error, -1 is returned, and errno is 
set appropriately. 
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ERRORS 

einval dev does not refer to a device containing a mounted filesystem. 

efault ubuf points outside of your accessible address space. 

enosys The mounted filesystem referenced by dev does not support this operation, or any version of Linux 

before 1.3.16. 

NOTES 

ustat has been provided for compatibility only. All new programs should usestatfs(2) instead. 

HISTORY 

ustat was first implemented in Linux 1.3.16. All versions of Linux before 1.3.16 will return enosys. 

C0NF0RMST0 

System V 

SEE ALSO 

statfs(2), stat(2) 

Linux 1.3.16, 9Augustl995 


utime,utimes 

utime, utimes— Change access and/or modification times of an inode 

SYNOPSIS 

#include <sys/types.h> 

#include <utime.h> 

int utime(const char filename, struct utimbuf *buf); 

#include <sys/time.h> 

int utimes(char *f i I e na me , struct timeval *tvp); 

DESCRIPTION 

utime changes the access and modification times of the inode specified by f i i e n a me to the act i me and modti me fields of buf, 
respectively. If buf isN U LL, the access and modification ti mes of the fi le are set to the current time. The utimbuf structure is 

struct utimbuf { 

time_t actime; /* access time */ 
time_t modtime; /* modification time */ 

}; 

In the Linux DLL 4.4.1 libraries, utimes is just a wrapper for utime, tvp[ 0 ].tv_sec isact i me, and t vp [i ] .t v_sec is mo d t i me. 
The timeval structure is 

struct timeval { 

long tv_sec; /* seconds */ 

long tv_usec; /* microseconds */ 

}; 

RETURN VALUE 

On success, e is returned. On error, -i isreturned, and errno is set appropriately. 



vm86 



ERRORS 

Other errors may occur. 

eaccess Permission to write thefile is denied. 

ENOENT f i I ename does not exist. 

C0NF0RMST0 

utime: SVID, POSIX 
utimes:BSD 4.3 

SEE ALSO 

stat(2) 


Linux, 10 ]unel995 


vhangup 

vhangup— Virtually hangs up the current tty 

SYNOPSIS 

#include <unistd.h> 
int vhangup(void); 

DESCRIPTION 

vhangup simulates a hangup on the current terminal. This call arranges for other users to have a clean tty at login time 

RETURN VALUE 

O n success, 0 is returned. 0 n error, -1 is returned, and errno isset appropriately. 

ERRORS 

eperm The user is not the superuser. 

SEE ALSO 

init(8) 

Linux0.99.11, 24]ulyl993 


vm86 

vm86— Enters virtual 8086 mode 

SYNOPSIS 

#include <sys/vm86.h> 

int vm86(struct vm86_struct * info); 

DESCRIPTION 

Enter VM 86 mode with information as specified in i nf 0 : 

struct vm86_struct { 

struct vm86_regs regs; 
unsigned long flags; 
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unsigned long screen_bitmap; 

}; 

struct vm86_regs { 

/* 

* normal regs, with special meaning for the segment descriptors.. 

*/ 

long ebx; 
long ecx; 
long edx; 
long esi; 
long edi; 
long ebp; 
long eax; 

long_null_ds; 

long_null_es; 

long _null_fs; 

long_null_gs; 

long orig_eax; 
long eip; 
long cs; 
long eflags; 
long esp; 
long ss; 

/* 

* these are specific to v86 mode: 

*/ 

long es; 
long ds; 
long fs; 
long gs; 

}; 

these are specific to v86 mode: 

/ 

long es; 
long ds; 
long fs; 
long gs; 

}; 

RETURN VALUE 

O n success, 0 is returned. 0 n error, -1 is returned, and errno isset appropriately. 

ERRORS 

eperm Saved kernel stack exists. 



Linux0.99.11, 24July 1993 


wait, waitpid 

wait, waitpid— W ait for process termination 

SYNOPSIS 


#include <sys/types.h> 
#include <sys/wait.h> 



wait, waitpid 

pid_t wait(int *st at us ) 

pid_t waitpid(pid_t pi d ,int*st at us ,int options); 

DESCRIPTION 

Thewait function suspends execution of the current process until a chi Id has exited, or until a signal is delivered whose 
action is to terminate the current processor to call a signal-handling function. If a child has already exited by the time of the 
call (a so-called zombie process), the function returns immediately. Any system resources used by the chi Id are freed. 

The waitpid function suspends execution of the current process until a child as specified by the pi d argument has exited, or 
until a signal is delivered whose action is to terminate the current processor to call a signal-handling function. Just as with 
wait, if a child requested by pi d has already exited by the time of the cal I, the function returns immediately. Any system 
resources used by the chi Id are freed. 

Thevalueof pi d can be oneof the following: 

< -i Waitforany child process whose process group ID is equal to the absolute value of p i d. 

-i Waitforany child process; thisisthesamebehaviorthatwait exhibits. 

0 Waitforany child process whose process group ID is equal to that of the calling process. 

> 0 Wait for the child whose process ID is equal to the value of pi d. 

T he value of opt i ons isan OR of zero or moreof thefollowing constants: 
wnohang Return immediately if no child hasexited. 

wuntraced Also return for children that are stopped and whose status has not been reported. 

If status is not null, wait or waitpid stores status information in the location pointed to by stati oc. 

This status can be evaluated with thefollowing macros (these macros take the stat buffer as an argument— not a pointer to 
the buffer!): 

wi fexited (st at us ) Isnonzero ifthechild exited normally. 

wExusTATus(st at us ) Evaluates to the least significant eight bits of the return code of the chi Id that terminated, which 

may have been set as the argument to a cal I to exito or as the argument for a return statement 
in the main program. This macro can only be evaluated if wifexited returned nonzero. 
wiFsiGNALED(st at us ) Returns true ifthechild process exited because of a signal that was not caught. 

wtermsig (st at us ) Returns the number of the signal that caused the chi Id process to terminate. This macro can 

only be evaluated if wifsignaled returned nonzero. 

wiFSTOPPED(st at us ) Returns true ifthechild process that caused the return is currently stopped; this is only possible 

if the call was done using wuntraced. 

wsTOPSiG(st at us ) Returns the number of thesignal that caused thechild to stop. This macro can only be 

evaluated if wifstopped returned nonzero. 

RETURN VALUE 

The process ID of thechild that exited returns-i on error or 0 if wnohang was used and no child was available (in which case 
errno issetto an appropriate value). 

ERRORS 

echild If thechild process specified in pi d does not exist. 

eperm If the effective user ID of the calling process does not match that of the process being waited 

for, and the effective user ID of the calling process isnot that of thesuperuser. 
erestartsys If wnohang was notset and an unblocked signal or a sigchld was caught; this is an extension to 

thePOSIX.1 standard. 
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CONFORMSTO 

POSIX.1 

SEE ALSO 

signal(2), wait4(2), signal(7) 


Linux, 24July 1993 


wait3, wait4 

wait3,wait4— Wait for process termination, BSD style 

SYNOPSIS 

#define _USE_BSD 
#include <sys/types.h> 

#include <sys/resource.h> 

#include <sys/wait.h> 

pid_t wait3(int *s t a t u s , int options, 

struct rusage *r usage); 

pid_t wait4(pid_t pi d ,int*st at us ,int options, 
struct rusage *rusage); 


DESCRIPTION 

Thewait3 function suspends execution of the current process until a child has exited, or until a signal is delivered whose 
action is to terminate the current processor to call a signal-handling function. If a child has already exited by the time of the 
call (a zombie process), the function returns immediately. Any system resources used by the chi Id are freed. 

T he wait4 function suspends execution ofthecurrent processuntil achild as specified by the pi d argument has exited, or 
until a signal is delivered whose action is to terminate the current processor to call a signal-handling function. If achild as 
requested by pi d has already exited by the time of the call (a zombie process), the function returns immediately. Any system 
resources used by the chi Id are freed. 

The value of pi d can be one of the following: 

< -i Waitforany child process whose process group ID is equal to the absolute value of p i d. 

-i Wait for any child process; this is equivalent to calling wait3. 

0 Waitforany child process whose process group ID is equal to that of the calling process. 

> 0 Wait for the child whose process ID is equal to the value of pi d. 

T he value of opt i ons isan exclusiveOR of zero or moreof thefollowing constants: 

wnohang Return immediately if no child isthereto be waited for. 

wuntraced Also return for children that are stopped and whose status has not been reported. 


If status is not null, wait3 and wait4 store status information in the location pointed to bystati oc. 


This status can be evaluated with thefollowing macros: 


WIFEXITED(*st at us) 
WEXITSTATUS(‘status) 


WIFSIGNALED(*s t at US) 
WTERMSIG(*S t a t u s ) 


Is nonzero ifthechild exited normally. 

Evaluates to the least significant eight bits of the return code of the chi Id that terminated, which 
may have been set as the argument to a cal I to exit or as the argument for a return statement in 
the main program. This macro can only be evaluated if wifexited returned nonzero. 

Returns true ifthechild process exited because of a signal that was not caught. 

Returns the number of the signal that caused the chi Id process to terminate. This macro can 
only be evaluated if wifsignaled returned nonzero. 



write 



wiFSTOPPED(*st at us ) Returns true if the child process that caused the return is currently stopped; this is only possible 

if the call was done usingwuNTRACED. 

wstopsig(*s t at us ) Returns the number of the signal that caused the chi Id to stop. This macro can only be 

evaluated ifwiFSTOPPED returned nonzero. If rusage isnotNun, thestruct rusage as defined in 
<sys/resource.h> it points to will be filled with accounting information. Seegetrusage(2) for 
details. 


RETURN VALUE 

These calls return the process ID of the chi Id that exited, -i on error, oro if wnohang was used and no child was available (in 
which caseermo will be set appropriately). 


ERRORS 

ECHILD 

EPERM 

ERESTARTSYS 


If the child process specified in pi d does not exist. 

If the effective user ID of the calling process does not match that of the process being waited 
for, and the effective user ID of the calling process is not that of the superuser. 

If wnohang was not set and an unblocked signal or a sigchld was caught; this is an extension to 
thePOSIX.1 standard. 


C0NF0RMST0 

POSIX.1 

SEE ALSO 

signal(2), getrusage(2), wait(2), signal(7) 


Linux, 24 July 1993 


write 

write— W rites to a file descriptor 

SYNOPSIS 

#include <unistd.h> 

ssize_t write(int f d, const void *buf , size_t count); 

DESCRIPTION 

write writes up to count bytes to the file referenced by the file descriptor fd from the buffer starting at but . PO SIX requires 
that a read o that can be proved to occur after a write o returned returns the new data. N otethat not all filesystems are 
POSIX conforming. 

RETURN VALUE 

On success, the number of bytes written is returned (0 indicates nothing was written). On error, -1 is returned, and errno is 
set appropriately. If count is 0 and the file descriptor refers to a regular file, 0 will be returned without causing any other 
effect. For a special file, the results are not portable. 

ERRORS 

ebadf fd is not a valid file descriptor or is not open for writing. 

einval fd isattached to an object that is unsuitable for writing. 

buf isoutside your accessible address space. 


EFAULT 
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epipe f d is connected to a pipe or socket whose reading end is closed. W hen this happens, the writing 

process will receive a sigpipe signal; if it catches, blocks, or ignores this the error epipe is 
returned. 

eagain N on-blocking I/O has been selected using o_nonblock, and there was no room in the pipe or 

socket connected to f d to write thedata immediately. 

eintr The call was interrupted by a signal before any data was written. 

enospc The device containing the file referred to by f d has no room for the data. 

Other errors may occur, depending on the object connected to f d. 

C0NF0RMST0 

SVID, AT&T, POSIX, X/OPEN , BSD 4.3 

SEE ALSO 

open(2), read(2), fcntl(2), close(2), lseek(2), select(2), ioctl(2), fsync(2), fwrite(3) 

Linux, 13 January 1996 
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Intro 

DESCRIPTION 

This chapter describes all the library functions, excluding the library functions described in Part 2, which implement system 
calls The various function groups are identified by a letter that is appended to the chapter number: 

(3C) These functions-the functions from Chapter 2 and from Chapter 3S—are contained in the C standard 

library libe, which will be used by cc(l) by default. 

(3S) T hese functions are parts of the stdio(3S) library. They are contained in the standard C library libc. 

(3M ) These functions are contained in the arithmetic library ubm. They areused by the f77(l) FORTRAN 

compiler by default, but not by the cc(l) C compiler, which needs the option -i m. 

(3F) These functions are part of the FORT RAN library iibF77. There are no special compiler flags needed to 

use these functions. 

(3X) Various special libraries. The manual pages documenting their functions specify the library names. 

AUTHORS 

Look at the header of the manual page for the author(s) and copyright conditions. N ote that these can be different from page 
to page! 

Linux, 13 December 1995 


abort 

abort— C auses abnormal program termination 

SYNOPSIS 

#include <stdlib.h> 
void abort(void); 

DESCRIPTION 

The abort o function causes abnormal program termination unless the signal sigabort is caught and the signal handler does 
not return. If the abort o function causes program termination, all open streams are closed and flushed. 

If the sigabort function is blocked or ignored, the abort o function will still override it. 

RETURN VALUE 

The abort o function never returns 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

sigaction(2), exit(3) 

GNU, 12 April 1993 


abs 

abs— C omputes the absolute value of an integer 



acosh 



SYNOPSIS 

#include <stdlib.h> 
int abs(int j ); 

DESCRIPTION 

Theabso function computes the absolute value of the integer argument]. 

RETURN VALUE 

Returns the absolute value of the integer argument. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

NOTES 

T rying to take the absolute value of the most negative i nteger is not defined. 

SEE ALSO 

ceil(3), floor(3), fabs(3), labs(3), rint(3) 

GNU, 6Junel993 


acos 

acos— Arc cosine function 

SYNOPSIS 

#include <math.h> 
double acos(double x); 

DESCRIPTION 

T he acos o function calculates the arc cosineof x; that is the value whose cosine is x. If x falls outside the range-1 to 1, 
acos() failsand errno iSSet. 

RETURN VALUE 

Theacoso function returns the arc cosine in radians; the value is mathematically defi ned to be between 0 and pi (inclusive). 

ERRORS 

edom x is out of range. 

C0NF0RMST0 

SVID 3, PO SIX, BSD 4.3, ISO 9899 

SEE ALSO 

asin(3), atan(3), atan2(3), cos(3), sin(3), tan(3) 

8Junel993 

acosh 

acosh— I nverse hyperbolic cosine function 
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SYNOPSIS 

#include <math.h> 
double acosh(double x); 

DESCRIPTION 

T he acosh o function calculates the inverse hyperbolic cosine of x; that is the value whose hyperbolic cosineisx. If * is less 
than 1.0, acosh o returns not-a-number (N aN), and errno is set. 

ERRORS 

edom x is out of range. 

C0NF0RMST0 

SVID 3, PO SIX, BSD 4.3, ISO 9899 

SEE ALSO 

asinh(3), atanh(3), cosh(3), sinh(3), tanh(3) 

13Junel993 


alloca 

aiioca— M emory allocator 

SYNOPSIS 

#include <stdlib.h> 
void *alloca( size_t size); 

DESCRIPTION 

T he aiioca function allocates s i z e bytes of space in the stack frame of the caller. T his temporary space is automatically freed 
on return. 

RETURN VALUES 

The aiioca function returns a pointer to the beginning of the allocated space. If the allocation fails, a null pointer is 
returned. 

C0NF0RMST0 

There is a/idence that the aiioca function appeared in 32 v, pwb, pwb.2, 3bsd, and 4bsd. There is a man page for it in BSD 
4.3. Linux uses the GN U version. 

BUGS 

T he aiioca function is machine dependent. 

SEE ALSO 

brk(2), pagesize(2), calloc(3), malloc(3), realloc(3) 

GNU, 29 November 1993 


asin 


asm— Arc sine function 



assert 



SYNOPSIS 

#include <math.h> 
double asin(double x); 

DESCRIPTION 

Theasino function calculates the arc sine of x, which is the value whose sine is x. If x falls outside the range-1 to 1, asino 
fails and errno isset. 

RETURN VALUE 

Theasino function returns the arc sine in radians, and thevalue is mathematically defined to be between -pi/2 andpi /2 
(inclusive). 

ERRORS 

edom x is out of range. 

C0NF0RMST0 

SVID 3, PO SIX, BSD 4.3, ISO 9899 

SEE ALSO 

acos(3), atan(3), atan2(3), cos(3), sin(3), tan(3) 

8Junel993 


asinh 

asinh— I nverse hyperbolic sine function 

SYNOPSIS 

#include <math.h> 
double asinh(double x); 

DESCRIPTION 

T he asinh o function calculates the inverse hyperbolic sine of x— that is, the value whose hyperbolic sine isx. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

acosh(3), atanh(3), cosh(3), sinh(3), tanh(3) 

13Junel993 


assert 

assent— Abort the program if assertion isfalse 

SYNOPSIS 


#include <assert.h> 

void assert (int expression); 
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DESCRIPTION 

assert) ) prints an error messageto standard output and terminates the program by calling abort)) ifexpressi on is false (that 
is, evaluates to 0). This only happens when the macro ndebug is undefined. 

RETURN VALUE 

No value is returned. 

CONFORMSTO 

ISO9899 (ANSI C) 

BUGS 

assert)) is implemented as a macro; if the expression tested has side effects, program behavior will be different depending on 
whether ndebug is defined. This may create H eisenbugs, which go away when debugging is turned on. 

SEE ALSO 

exit(3), abort(3) 

GNU, 4 April 1993 


atan 

atan— Arc tangent function 

SYNOPSIS 

#include <math.h> 
double atan(double x); 

DESCRIPTION 

Theatano function calculates the arc tangent of x — that is the value whose tangent is x . 

RETURN VALUE 

The atano function returns the arc tangent in radians, and the value is mathematically defined to be between -pi/2 and pi/2 
(inclusive). 

CONFORMSTO 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

acos(3), asin(3), atan2(3), cos(3), sin(3), tan(3) 

8Junel993 


atan2 

atan 2 — Arc tangent function of two variables 

SYNOPSIS 


#include <math.h> 

double atan2(double y, double x); 



atexit 



DESCRIPTION 

T he atan 2 ( ) function calculates the arc tangent of the two variables, * and y. It is similar to calculating the arc tangent of y/x, 
except that the sines of both arguments are used to determine the quadrant of the result. 

RETURN VALUE 

T he atan 2 ( ) function returnsthe result in radians, which is between -pi and pi (inclusive). 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

acos(3), asin(3), atan(3), cos(3), sin(3), tan(3) 

8 Junel993 


atanh 

atanh— I nverse hyperbolic tangent function 

SYNOPSIS 

#include <math.h> 
double atanh(double x); 

DESCRIPTION 

T he atanh o function calculates the inverse hyperbolic tangent of x ; that is the value whose hyperbolic tangent is x. If the 
absolute value of x isgreaterthan 1.0, acosho returns not-a-number (N aN), and emno isset. 

ERRORS 

edoh x is out of range. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

asinh(3), acosh(3), cosh(3), sinh(3), tanh(3) 

13Junel993 


atexit 

atexit— Register a function to be called at normal program termination 

SYNOPSIS 

#include <stdlib.h> 

int atexit(void *funct i on)(void)); 

DESCRIPTION 

Theatexito function registers the given function to be called at normal program termination, whether via exit(2) or via 
return from theprograrn'smain. Functions so registered are called in the reverse order of their registration; no arguments are 
passed. 
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RETURN VALUE 

T he atexit) (function returns the value 0 if successful; otherwise, thevalue-i isreturned, and theglobal variableerrno is set 
to indicate the error. 

ERRORS 

enomem Insufficient memory available to add the function. 

C0NF0RMST0 

SVID 3, BSD 4.3, ISO 9899 

SEE ALSO 

exit(3), on exit(3) 

GNU, 29 M arch 1993 


atof 

atof— C onvert a string to a double 

SYNOPSIS 

#include <stdlib.h> 

double atof(const char *nptr); 

DESCRIPTION 

T he atof 0 function converts the initial portion of the string pointed to by npt r to double. The behavior is the same as 

strtod(nptr, (char * *) NULL); 

except that atof <) does not detect errors. 

RETURN VALUE 

The converted value. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

atoi(3), atol(3), strtod(3), strtol(3), strtoul(3) 

GNU, 29 M arch 1993 


atoi 

atoi— C onvert a string to an integer 

SYNOPSIS 


#include <stdlib.h> 

int atoi(const char *nptr); 



bcmp 


899 


DESCRIPTION 

T he atoi () function converts the initial portion of the string pointed to by npt r to int. The behavior is the same as 
strtol(nptr, (char **)NULL, 10); 

except that atoi( ) does not detect errors. 

RETURN VALUE 

The converted value. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

atof(3), atol(3), strtod(3), strtol(3), strtoul(3) 

GNU, 29 M arch 1993 


atol 

atoi— Convert a string to a long integer 

SYNOPSIS 

#include <stdlib.h> 

long atol(const char *npt r ); 

DESCRIPTION 

Theatoio function converts the initial portion of the string pointed to by npt r to long. The behavior isthesameas 
strtol(nptr, (char **)NULL, 10); 

except that atoi( ) does not detect errors 

RETURN VALUE 

The converted value. 

C0NF0RMST0 

SVID 3, PO SIX, BSD 4.3, ISO 9899 

SEE ALSO 

atof(3), atoi(3), strtod(3), strtol(3), strtoul(3) 

GNU, 29 M arch 1993 


bcmp 

bcmp— C ompare byte stri ngs 

SYNOPSIS 


#include <string.h> 

int bcmp(const void *sl, const void *s2, int n); 
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DESCRIPTION 

T he bcmp () function compares the first n bytes of the strings si and s 2 . If the two strings are equal, bcmpo returns 0 ; 
otherwise, it returns a nonzero result. If n iso, thetwo strings are assumed to be equal. 

RETURN VALUE 

The bcmpo function returnse if the strings are equal; otherwise, a nonzero result is returned. 

CONFORMSTO 

4.3BSD .Thisfunction isdeprecated— use memcmp in new programs. 

SEE ALSO 

memcmp(3), strcasecmp(3), strcmp(3), strcoll(3), strncmp(3), strncasecmp(3) 

GNU, 9 April 1993 


bcopy 

bcopy— Copy byte strings 

SYNOPSIS 

#include <string.h> 

void bcopy (const void *src, void*dest , int n); 

DESCRIPTION 

T he bcopy 0 function copies the first n bytes of the source stri ng s r c to the destination string dest . If n isO, no bytes are 
copied. 

RETURN VALUE 

The bcopy 0 function returns no value. 

CONFORMSTO 

4.3BSD .Thisfunction isdeprecated— usememcpy in new programs. 

SEE ALSO 

memccpy(3), memcpy(3), memmove(3), strcpy(3), strncpy(3) 

GNU, 9 April 1993 


bsearch 

bsearch — Binary search of a sorted array. 

SYNOPSIS 

#include <stdlib.h> 

void *bsearch(const void *key, const void *base, size_t nmemb, 
size_t si ze,int(*compar )(const void *, const void *)); 

DESCRIPTION 

The bsearch 0 function searches an array of nmemb objects, the initial member of which is pointed to by base, for a member 
that matches the object pointed to by key. The size of each member of the array is specified by si ze. 

The contents of the array should be in ascending sorted order according to the comparison function referenced by c 0 mp a r. 



htonl, htons, ntohl, ntohs 



T he c o mpa r routine is expected to have two arguments that point to the key object and to an array member, in that order, and 
should return an integer less than, equal to, or greater than 0, respectively, if the key object is found to be less than, match, or 
be greater than the array member. 

RETURN VALUE 

Thebsearcho function returns a pointer to a matching member of the array, or null if no match is found. If there are 
multiple elements that match the key, the element returned is unspecified. 

C0NF0RMST0 

SVID 3, BSD 4.3, ISO 9899 

SEE ALSO 

qsort(3) 

GNU, 29 March 1993 

bcmp, bcopy, bzero, memccpy, memchr, memcmp, memcpy, memf rob, 
memmem,memmove,memset 

bcmp, bcopy, bzero, memccpy, memchr, memcmp, memcpy, memf rob, memmem, memmove, memset— Byte String operations 

SYNOPSIS 

#include <string.h> 

int bcmp(const void *sl, const void *s2, int n); 
void bcopy(const void *src, void *dest , int n); 
void bzero(void *s, int n); 

void *memccpy(void *dest , const void *src, int c, size_t n); 

void *memchr(const void *s , int c, size_t n); 

int memcmp(const void *sl, const void *s2, size_t n); 

void *memcpy(void *dest , const void *src, size_t n); 

void *memfrob(void *s , size_t n); 

void *memmem(const void *needle, size_t needlelen, 

const void *haystack, size_t haystacklen); 

void *memmove(void *dest , const void *src, size_t n); 

void *memset(void *s, int c, size_t n); 

DESCRIPTION 

The byte string functions perform operations on strings that are not NULL terminated. See the individual man pages for 
descriptions of each function. 

SEE ALSO 

bcmp(3), bcopy(3), bzero(3), memccpy(3), memchr(3), memcmp(3), memcpy(3), memfrob(3), memmem(3), memmbve(3), memset(3) 

GNU, 12 April 1993 


htonl, htons, ntohl, ntohs 

htom, htons, ntohl, ntohs— C onvert values between host and network byte order 

SYNOPSIS 


#include <netinet/in.h> 

unsigned long int htonl(unsigned long int host long); 
unsigned short int htons(unsigned short int hostshort ); 
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unsigned long int ntohl(unsigned long int net long); 
unsigned short int ntohs(unsigned short int netshort ); 

DESCRIPTION 

Thehtomo function converts the long integer host I ong from host byte order to network byte order. 

Thehtonso function converts the short integer host short from host byte order to network byte order. 

Thentohio function converts the long integer net i ong from network byte order to host byte order. 

T he ntohs o function converts the short integer netshort from network byte order to host byte order. 

0 n the i 80x86, the host byte order is least significant byte first, whereas the network byte order, as used on the Internet, is 
most significant byte first. 

C0NF0RMST0 

BSD 4.3 


SEE ALSO 

gethostbyname(3), getservent(3) 


BSD, 15 April 1993 


bzero 

bzero— Writes os to a byte string 

SYNOPSIS 

#include <string.h> 
void bzero(void *s, int n); 

DESCRIPTION 

Thebzenoo function setsthefirst n bytes of the byte strings toO. 

RETURN VALUE 

Thebzenoo function returns no value. 

C0NF0RMST0 

4.3BSD .Thisfunction isdeprecated— usememset in new programs. 

SEE ALSO 

memset(3), swab(3) 

GNU, 9 April 1993 


catgets 

catgets— Gets message from a message catalog 

SYNOPSIS 

#include <features.h> 

#include <nl_types.h> 

char *catgets(nl_catd catalog, int set_number, int 
message_number, char *message); 



catopen, catclose 



DESCRIPTION 

catgets/ ) reads the message message_number, in S6t set_number, from the message Catalog identified by catalog, (catalog isa 
catalog descriptor returned from an earlier call to catopen(3).) The fourth argument message points to a default message 
string that will be returned by catgetso if the identified message catalog is not currently open or is damaged. The message 
text is contained in an internal buffer area and should be copied by the application if it is to be saved or modified. The return 
string is always terminated with a null byte. 

RETURN VALUES 

On success, catgetso returns a pointer to an internal buffer area containingthe null-terminated message string, catgetso 
returns a pointer to message if it fails because the message catalog specified by catalog is not currently open. Otherwise, 
catgetso returns a pointer to an empty string if the message catalog is available but does not contain the specified message. 

NOTES 

These functions are only available in iibc.so.4.4.4c and above. 

SEE ALSO 

catopen(3), setlocale(3) 

29 N ovember 1993 


catopen,catclose 

catopen, catclose— 0 pen/close a message catalog 

SYNOPSIS 

#include <features.h> 

#include <nl_types.h> 

nl catd catopen(char *name, int flag); 

void catclose(nl_catd catalog); 

DESCRIPTION 

catopeno opens a message catalog and returnsa catalog descriptor, name specifies the name of the message catalog to be 
opened. If name specifies an absolute path (that is, contains a /), name specifies a pathnamefor the message catalog. Otherwise, 
the environment variable nlspath is used, with name substituted for %n (see iocaie{5)). If nlspath does not exist in the 
environment, or if a message catalog cannot beopened in any of the paths specified by nlspath, thefollowing pathsare 
searched in order: 

/etc/locale/LC_MESSAGES 
/usr/lib/locale/LCMESSAGES 
/usr/lib/locale/name/LC_MESSAGES 

In all cases, lc_messages stands for the current setting of the lc_messages category of locale from a previous call to 
setiocaieo and defaults to theC" locale. In the last search path, name refers to the catalog name. 

T he f i a g argument to catopen isused to indicate the type of loading desired. Thisshould be either MCLoadByset or MCLoadAii. 
The former value indicates that only the required set from the catalog is loaded into memory when needed, whereas the latter 
causes the initial call to catopen/) to load the entirecatalog into memory. 

catclose/) closes the message catalog identified by cat ai og. It invalidates any subsequent references to the message catalog 
defined by cat ai og. 

RETURN VALUES 

catopen/) returns a message catalog descriptor of type m_catd on success. 0 n failure it returns -i. 
catclose/) returnso on success, or -i on failure. 
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NOTES 

These functions are only avail able in libc.so.4.4.4c and above. In the case of Linux, the catalog descri ptor ni_catd is actually 
an area of memory assigned bymmapo and not a file descriptor, thus allowing catalogs to be shared. 

SEE ALSO 

catgets(3), setlocale(3) 

30 N ovember 1993 


ceil 

ceil— Smallest integral value not less than x 

SYNOPSIS 

#include <math.h> 
double ceil (double x); 

DESCRIPTION 

Theceiio function rounds upx tothenearest integer, returning that value as a double. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

abs(3), fabs(3), floor(3), labs(3), rint(3) 

6 Junel993 


clientlib 

ciientiib— N NTP clientlib part of InterN etN ewslibrary 

SYNOPSIS 

extern FILE *ser_rd_fp; 

extern FILE *ser_wr_fp; 

extern char ser_line[]; 

char * getserverbyfile(f i I e); 

char *file; int server_init(host ); 

char *host; 

int handle_server_response(response, host); 
int reponse; 
char *h o s t ; 

void put_server(text ); 
char *text ; 

int get_server(buff, buffsize); 
char *buff ; 
int buffsize; 
void close_server(); 

DESCRIPTION 

The routines descri bed in this manual page are part of the InterN etN ews library, iibinn(3). They are replacements for the 
clientlib part of theN NTP distribution, and are intended to be used in building programs such asrrn. 



closdir 



getserverbyfiie callsGetcontigvaiue to get the name of the local N NTP server. It returns a pointer to static space. The f i e 
parameter is ignored. 

server_init opens a connect to the N N T P server at the specified host. It returns the server's response code or -i on error. If 
a connection was made, ser_rd_fp and ser_wr_fp can be used to read from and write to the server, respectively, and ser_iine 
will contain the server's response. ser_iine can also beused in other routines. 

handie_server_response decodes the response, which comes from the server on host . If the client is authorized, it returns 0 . A 
client that is only allowed to read is authorized, but handie_server_response will print a message on the standard output. If 
the client is not authorized to talk to the server, a message is printed, and the routine returns - 1 . 

put_server sends the text in buff to the server, adding the necessary N NTP line terminators and flushing the I/O buffer. 

get_server reads a line of text from the server into buff , reading at most buff si ze characters. Any trailing \r\n terminators 
are stripped off. get_server returns -1 on error. 

ciose_server sends a quit command to the server and closes the connection. 

HISTORY 

W ritten by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

libinn(3) 

clock 

clock— D etermine processor time 

SYNOPSIS 

#include <time.h> 
clock_t clock(void); 

DESCRIPTION 

The clock)) function returnsan approximation of processor timeused by the program. 

RETURN VALUE 

The value returned is the CPU timeused so far as a ciock_t; to get the number of seconds used, divide by clocks_per_sec. 

C0NF0RMST0 

ANSI C 

BUGS 

TheC standard allows for arbitrary values at the start of the program; take the difference between the value returned from a 
call to ciocko at the start of the program and the value returned at the end for maximum portability. 

Thetimeso function call returns more information. 

SEE ALSO 

times(2) 

GNU, 21 April 1993 


closedir 

ciosedii — C lose a di rectory 
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SYNOPSIS 

#include <sys/types.h> 

#include <dirent.h> 
int closedir(DIR *di r ); 

DESCRIPTION 

Theciosediro function closes the directory stream associated with di r. T he directory stream descriptor di r is not available 
after this call. 

RETURN VALUE 

Theciosediro function returns 0 on success or -i on failure. 

ERRORS 

ebadf Invalid directory stream descriptor d i r. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3 

SEE ALSO 

close(2), opendir(3), readdir(3), rewinddir(3), seekdir(3), telldir(3), scandir(3) 

11Junel995 


confstr 

confstr— Get configuration-dependent string variables 

SYNOPSIS 

#define _USE_POSIX_2 
#include <unistd.h> 

size_t confstr (int name, char *buf , size_t len); 

DESCRIPTION 

confstr< ) gets the value of configuration-dependent string variables. 

The name argument is the system vari able to be Queried. The follow! ng vari ables are supported! 

cs_path A value for the path variablethat indicates where all the PO SIX .2 standard utilities can be found. 

If buf is not NULL, and i e n isnot 0, confstro copies the value of the stri ng to buf truncated to len-1 characters if necessary, 
with a null character as termination. This can be detected by comparing the return value of confstro against i en. 

If I en iso and buf iSNULL, confstr)) just returns the value in Return Value. 

RETURN VALUE 

If name does not correspond to a valid configuration variable confstro returnso. 

EXAMPLES 

The foil owing codefragment determines the path where you can find the PO SIX.2 system utilities: 

char *pathbuf; size_t n; 
n = confstr(_CS_PATH,NULL,(size_t)0); 
if ((pathbuf = malloc(n)) == NULL) abort(); 
confstr(_CS_PATH, pathbuf, n); 
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ERRORS 

If the value Of name isinvalid, errno i s set to EINVAL. 

C0NF0RMST0 

Proposed POSIX.2 

BUGS 

POSIX.2 is not yet an approved standard; the information in this man page is subject to change. 

SEE ALSO 

sh( 1), exec(2), system(3) 

GNU, 17 April 1993 

copysign 

copysign— Copies thesign of a number 

SYNOPSIS 

#include <math.h> 

double copysign(double x, double y); 

DESCRIPTION 

The copysigno function returns a value whose absolute value matches*, but whose sign matches that of y. 

C0NF0RMST0 

BSD 4.3 

GNU, 6Junel993 


COS 

cos— Cosine function 

SYNOPSIS 

#include <math.h> 
double cos(double x); 

DESCRIPTION 

Thecoso function returns the cosine of *, where x isgiven in radians. 

RETURN VALUE 

Thecoso function returns a value between -1 and 1. 

C0NF0RMST0 

SVID 3, PO SIX, BSD 4.3, ISO 9899 

SEE ALSO 

acos(3), asin(3), atan(3), atan2(3), sin(3), tan(3) 


8 Junel993 
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cosh 

cosh— H yperbolic cosinefunction 

SYNOPSIS 

#include <math.h> 
double cosh(double x); 

DESCRIPTION 

T he cosho function returns the hyperbolic cosine of x, which is defined mathematically as (exp(x)+exp(-x))/ 2 . 

C0NF0RMST0 

SVID 3, PO SIX, BSD 4.3, ISO 9899 

SEE ALSO 

acosh(3), asinh(3), atanh(3), sinh(3), tanh(3) 

13Junel993 


crypt 

crypt— Password and data encryption 

SYNOPSIS 

#include <unistd.h> 

char *crypt(const char *key, const char *s a 11 ); 

DESCRIPTION 

crypt isthe password-encryption function. Itisbased on the Data Encryption Standard algorithm, with variations intended 
(among other things) to discourage the use of hardware implementations of a key search. 

key isa user's typed password. 

salt is a two-character string chosen fromtheset [a-zA-zo-9. / ]. T his string is used to perturb the algorithm in oneof4,096 
different ways. 

By taking the lowest seven bits of each character of the key, a 56-bit key is obtained. This 56-bit key is used to repeatedly 
encrypt a constant string (usually a string consisting of all «s). The returned value points to the encrypted password, a series 
of 13 printableASCII characters (with the first two characters representing the salt itself). The return value points to static 
data whose content is overwritten by each call. 

Warning: The key space consists of equal 7.2ei6 possible values. Exhaustive searches of this key space are possible using 
massively parallel computers. Software, such ascrack(l), is available to search the portion of this key space that is generally 
used by humansfor passwords. H ence, password selection should, at minimum, avoid common words and names. Using a 
passwd(l) program that checks for crackable passwords duri ng the selection process is recommended. 

TheD ES algorithm itself has a few quirks that make using the crypt(3) interface a very poor choice for anything other than 
password authentication. If you are planning to usethecrypt(3) interface for a cryptography project, don't do it; get a good 
book on encryption and one of the widely available D ES libraries instead. 

C0NF0RMST0 

SVID,X/OPEN, BSD 4.3 
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SEE ALSO 

login(l), passwd(l), encrypt(3), getpass(3), passwd(5) 


3 September 1994 


ctermid 

ctermid— Gets controlling terminal name 

SYNOPSIS 

#include <stdio.h> 
char *ctermid(char *s); 

DESCRIPTION 

ctermid o returns a string that is the path name for the current controlling terminal for this process. If s is null, astatic buffer 
is used; otherwise, s points to a buffer used to hold the terminal pathname. The symbolic constant L_ctermid is the 
maximum number of characters in the returned pathname 

RETURN VALUE 

This function returns the pointer to the pathname. 

C0NF0RMST0 

POSIX.1 

BUGS 

The path returned might not uniquely identify the controlling terminal; it might, for example be /dev/tty. 

It is not assured that the program can open the terminal. 

SEE ALSO 

ttyname(3) 

GNU, 6 April 1993 


asctime, ctime,gmtime,localtime,mktime 

asctime, ctime, gmtime, localtime, mktime —T ransform binary date and ti me to ASCII 

SYNOPSIS 

#include <time.h> 

char *asctime(const struct tm *t i mept r ); 
char *ctime( const time_t *t i me p); 
struct tm *gmtime(const time_t *t i mep); 
struct tm *localtime(const time_t *t i mep); 
time_t mktime(struct tm *t i mept r ); 
extern char *t zname [2]; 
long int t i mezone; 
extern int daylight ; 

DESCRIPTION 

Thectimeo, gmtimeo, and localtime ((functions all takean argument of data type time_t, which represents calendar time. 
When interpreted as an absolute time value it represents the number of seconds elapsed since 00:00:00 on January 1,1970, 
Coordinated Universal Time(UTC). 
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T he asctime() and mktimeo functions both take an argument representing broken-down time, which is a binary representa¬ 
tion separated into year, month, day, and so on. Broken-down ti me is stored in the structure! m, which isdefined in <time.h> 
as follows: 

struct tm 
{ 

int tm_sec; /* seconds */ 

int tmjnin; /* minutes */ 

int tm_hour; /* hours */ 

int tmjnday; /* day of the month */ 

int tm_mon; /* month */ 

int tm_year; /* year */ 

int tm_wday; /* day of the week */ 

int tm_yday; /* day in the year */ 

int tm_isdst; /* daylight saving time */ 

}; 


T he members of thet m structure are 

tm_sec T he number of seconds after the minute, normally in the range 0 to 59, but can be up to 61 to allow for 

leap seconds. 

tm_min T he number of minutes after the hour, in the range 0 to 59. 

tm_hour The number of hours past midnight, in the range 0 to 23. 

tm_mday T he day of the month, in the range 1 to 31. 

tmjnon T he number of monthssincej anuary, intherangeOto 11. 

tm_year T he number of years si nee 1900. 

tm wday T he number of days si nee Sunday, in the range 0 to 6. 

tm_yday T he number of days sincej anuary 1, in the range 0 to 365. 

tm_isdst A flag that indicates whether daylight savings time is in effect at the time described. The value is positive if 

daylight savingtime isin effect, 0 if itisnot, and negative if the information is not available. 

T he ctime( function converts the calendar ti me ti me p into a string of the form 

"Wed Jun 30 21:49:08 1993\n" 

Theabbreviationsforthedaysof theweek are sun, Mon , Tue, wed, Thu, fu, and sat. The abbreviations for the months are 
jan, Feb, Mar, Apr, May, jun, jui, Aug, sep, oct, Nov, and Dec. The return value points to a statically allocated string that might 
be overwritten by subsequent calls to any of the date and time functions. The function also sets the external variable tzname 
with information about the current time zone. 

T he gmtime( ) function converts the calendar ti me timep to broken-down time representation, expressed in Coordinated 
Universal Time(UTC). 

The localtime o function converts the calendar ti me ti mep to broken-time representation, expressed relative to the user's 
specified time zone. The function sets the external variablest z name with information about the current time zone ti mezone 
with the difference between Coordinated Universal Time and local standard time in seconds, and dayi i ght to a nonzero 
value if standard U .S. daylight saving time rules apply. 

Theasctimeo function converts the broken-down time value t i mept r into a string with the same format asetimeo. The 
return value points to a statically allocated string that might be overwritten by subsequent calls to any of the date and time 
functions 

The mktimeo function converts a broken-down time structure expressed as local time, to calendar time representation. The 
function ignores the specified contents of the structure members tm_wday and tm_yday and recomputes them from theother 
information in the broken-down timestructure Calling mktimeo also sets the external variable tzname with information 
about the current time zone. If the specified broken-down time cannot be represented as calendar time mktimeo returnsa 
value of <time_t) (-i) and does not alter thet m_#ijay and t m_yday membersof the broken-down timestructure. 
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CONFORMSTO 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

date(l), gettimeofday(2), time(2), tzset(3), difftime(3), strftime(3), newctime(3) 

BSD, 26 April 1996 


difftime 

difftime— C alculates time difference 

SYNOPSIS 

#include <time.h> 

double difftime(time_t timel, time_t t i me0); 

DESCRIPTION 

The difftime o function returns the number of seconds elapsed between timet i me 1 and timet i meo. The two times are 
specified in calendar time which represents the time elapsed since 00:00:00 onjanuary 1,1970, Coordinated Universal 
Time(UTC). 

conforms™ 

SVID 3, BSD 4.3, ISO 9899 

SEE ALSO 

date(l), gettimeofday(2), time(2), ctime(3), gmtime(3), localtime(3) 

GNU, 2July 1993 


div 

div— C omputes the quotient and remainder of integer division 

SYNOPSIS 

#include <stdlib.h> 

div_t div(int numer , int denom) ; 

DESCRIPTION 

Thedivo function cornputesthevaluenumer/denom and returns the quotient and remainder in a structure named div_t that 
contains two integer members named pot andrem. 

RETURN VALUE 

Thediv_t structure. 

conforms™ 

SVID 3, BSD 4.3, ISO 9899 

SEE ALSO 

ldiv(3) 

6 Junel993 
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drand48, erand48, lrand48, nrand48, mrand48, j rand48, srand48, 
seed48,lcong48 

drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48, lcong48 —G enerate uniformly distributed pseudo¬ 
random numbers 

SYNOPSIS 

#include <stdlib.h> 
double drand48(void); 

double erand48(unsigned short int xsubi [3]); 
long int lrand48(void); 

long int nrand48(unsigned short int xsubi [3]); 
long int mrand48(void); 

long int jrand48(unsigned short int xsubi [3]); 
void srand48(long int seedval ); 

unsigned short int * seed48(unsigned short int seed 16v [3]); 
void lcong48(unsigned short int par am[7]); 

DESCRIPTION 

These functions generate pseudo-random numbers using the linear congruential algorithm and 48-bit integer arithmetic. 

T he drand48() and erand48() functions return non-negative double-precision floating-point values uniformly distributed 
between [0.0,1.0], 

T he irand48( ) and nrand48() functions return non-negative long integers uniformly distributed between 0 and 2 / '31. 

T he mrand48( ) and jrand48( ) functions return signed long integers uniformly distributed between -2^31 and 2^31. 

The srand48( ) ,seed48( ), and icong48() functions are initialization functions, oneofwhich should be called beforeusing 
drand48(), lrand48(), 0rmrand49(). T he functions erand48( ) , nrand48(), and jrand48() do not require an initialization 
function to be called first. 

All the functions work by generating a sequence of 48-bit integers, Xi, according to the linear congruential formula 
X/ +1 =(aX/-k:) modm, where/ >=0 

The parameter m=2-48; hence 48-bit integer arithmetic is performed. Unless icong48() is called, a and care given by 

a = 0X5DEECE66D 
C = 0xB 

The value returned by any of the functions drand48(), erand48(), irand48(), nrand48(), mrand48(), or ] rand48( ) is computed 
by fi rst generati ng the next 48-bit xi i n the sequence. T hen the appropriate number of bits, accordi ng to the type of data 
item to be returned, is copied from the high-order bits of xi and transformed into the returned value. 

The functions drand48(), irand48(), and mrand48() store the last 48-bit xi generated in an internal buffer. The functions 
erand48(), nrand48(), and jrand48() requi re the calli ng program to provide storage for the successivexi values in the array 
argument xsubi. The functions are initialized by placing the initial value of xi into the array before calling the function for 
the first time. 

The initializer function srand48() sets the high-order 32 bits of xi to theargumentseedvai .The low-order 16 bits are set to 
the arbitrary value 0x330E. 

The initializer function seed48() sets the value of xi to the 48-bit value specified in the array argument seedl6v. The 
previous value of Xi is copied into an internal buffer and a pointer to this buffer is returned by seed48(). 

The initialization function icong48() allowstheuserto specify initial values for xi, a and c. Array argument elements 
param[0-2] specify xi, param[3-5] specify a, and param[6] specifi esc. After icong48() has been called, a subsequent call to 
either srand48() or seed48( ) will restore the standard values of a andc. 
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CONFORMSTO 

svid 3 

NOTES 

These functions are declared obsolete by SVID 3, which states that rand(3) should beused instead. 

SEE ALSO 

rand(3), randcm(3) 

2]ulyl993 


drem 

drem— Floating-point remainder function 

SYNOPSIS 

#include <math.h> 

double drem(double x, double y); 


DESCRIPTION 

Thedremo function computes the remainder of dividing* by y. The return value isx-n*y, wheren isthe quotient of x 
divided byy, rounded to the nearest integer. If the quotient is itisrounded totheeven number. 

RETURN VALUE 

Thedremo function returns the remainder unless y is 0, in which case the function fails and errno is set. 

ERRORS 

edom T he denominator y iso. 

conforms™ 

BSD 4.3 


SEE ALSO 

fmod(3) 


6 Junel993 


ecvt,fcvt 

ecvt, fcvt— Convert a floating-point number to a string 

SYNOPSIS 

#include <stdlib.h> 

char *ecvt(double number , size_t ndigi ts,int*decpt ,int*si gn); 
char *fcvt(double number , size_t ndi gi ts ,int*decpt ,int*si gn); 

DESCRIPTION 

T he ecvt o function converts number to a Nun-terminated string of ndi gits digits and returns a pointer to the string. The 
string itself does not contain a decimal point; however, the position of the deci mal point relative to the start of thestring is 
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stored in dec pt . A negative value for decpt means that the decimal point is to the left of the start of the string. If the sign of 
number is negative, sign is set to a nonzero value; otherwise, it's set to 0 . 

Thetcvto function is identical to ecvto, except that n d i gits specifies the number of digits after the decimal point. 

RETURN VALUE 

Both the ecvto and fcvto functions return a pointer to a static string containing the ASCI I representation of number .The 
static string isoverwritten by each call to ecvto or fcvto. 

SEE ALSO 

gcvt(3), sprintf(3) 

28 March 1993 


erf, erf c 

erf, erfc— Error function and complementary error function 

SYNOPSIS 

#include <math.h> 
double erf(double *); 
double erfc (double *); 

DESCRIPTION 

Theerfo function returns the error fundi on of*, defined as 
erf(x) = 2/sqrt(pi)* integral from 0 to x of exp(-1*t) dt 

T he erf c () function returns the complementary error function of x — that is, l.O-erf(x). 

C0NF0RMST0 

SVID 3, BSD 4.3 

SEE ALSO 

exp(3) 

BSD, 25Junel993 


execl,execlp, execle,exect,execv,execvp 

execl, execlp, execle, exect, execv, execvp— Execute a file 


SYNOPSIS 

#include <unistd.h> 
extern char **environ; 

int execl(const char *path, const char *arg, ...); 
int execlp(const char *fiI e, const char *arg, ...); 
int execle(const char *path, const char *arg, ...); 
int execlp(const char *fiIe, const char *arg, ...); 
int execle(const char *path, const char *arg, ...); 

int execle(const char *path, const char *arg , char * const e n v p [ ]) ; 
int exect(const char *pat h, char *const ar gv [ ]); 
int execv(const char *pat h, char *const ar gv [ ]); 
int execvp(const char *fiI e, char *const ar gv [ ]); 







exec/, execlp, execle, exert, execv, execvp 



DESCRIPTION 

The exec family of functions replaces the current process image with a new process image. The functions described in this 
manual page are front ends for the function execve(2). (See the manual page for execve for detailed information about the 
replacement of the current process.) 

Theinitial argument for these functions is the pathname of afilethat isto be executed. 

The const char *arg and subsequent ellipses in theexeci, execlp, and execle functions can bethought of asarga, argi,.... 
argn. T ogether they describea list of one or more pointers to null-terminated strings that represent the argument list 
available to the executed program. The first argument, by convention, should point to the file name associated with the file 
being executed. The list of arguments must be terminated by a null pointer. 

Theexect, execv, and execvp functions provide an array of pointers to null-terminated strings that represent the argument 
list available to the new program. The first argument, by convention, should point to the filename associated with the file 
being executed. The array of pointers must determinated by a null pointer. 

The execle and exect functions also specify the environment of the executed process by following the null pointer that 
terminatesthe list of arguments in the parameter list or the pointer to the a r gv array with an additional parameter. This 
additional parameter is an array of pointers to null-terminated strings and must determinated by a null pointer. The other 
functions take the environment for thenew process image from theexternal variableenvi ron in thecurrent process. 

Some of these functions have special semantics. 

The functions execlp and execvp will duplicate the actions of the shell in searching for an executable file if the specified 
filename does not contain a slash (/) character. The search path isthepath specified in the environment by thePATH variable. 
If this variable isn't specified, the default path /bin:/usr/bin : isused (isthistrue for Linux?). In addition, certain errors are 
treated specially. 

If permission is denied for a file (the attempted execve returned eacces), these functions will continue searching the rest of 
the search path. If no other file is found, however, they will return with the global variable errno set to eacces. 

If the header of a file isn't recognized (the attempted execve returned ENOEXEC), these functions will execute the shell with 
the path of thefileas its first argument. (If thisattempt fails no further searching is done.) 

If the file is currently busy (the attempted execve returned etxtbusy), these functions will sleep for several seconds periodi¬ 
cally re-attempting to execute the file. (Is this true for Linux?) 

Thefunction exect executes a file with the program-tracing facilities enabled (seeptrace(2)). 

RETURN VALUES 

If any of the exec functions returns an error will have occurred. The return value is-i, and the global variable errno will be 
set to indicate the error. 

FILES 

/bin/sh 

ERRORS 

execi, execle, execlp, and execvp may fail and st errno for any of the errors specified for the library functions execve(2) and 
malloc(3). 

exect and execv may fail and set errno for any of the errors specified for the library function execve(2). 

SEE ALSO 

sh( 1), execve(2), fork(2), trace(2), environ(5), ptrace(2) 

COMPATIBILITY 

H istorically, the default path for the execlp and execvp functions was /bin: /usr/bin. This was changed to place the current 
directory last to enhance system security. 
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The behavior of execip and execvp when errors occur while attempting to execute the file is historic practice, but has not 
traditionally been documented and is not specified bythePOSIX standard. 

T raditionally, the functions execip and execvp ignored all errors except for the ones described above and enomem and e 2 big, 
upon which they returned. They now return if any error other than the ones described in the "Errors" section occurs. 

STANDARDS 

execl, execv, execle, execip, and execvp conform to IEEE Stdl003.1-88 (PO SIX.1). 

BSD M an Page, 29 N ovember 1993 


errno 

errno — N umber of last error 

SYNOPSIS 

#include <errno.h> 
extern int errno; 

DESCRIPTION 

The integer errno is set by system calls (and some library functions) to indicatewhat went wrong. Its value issignificant only 
when the call returns an error (usually -1), and a library function that does succeed is allowed to changeerrno. 

Sometimes, when -i is also a legal return value, you have to set errno to e before the call in order to detect possible errors. 
POSIX lists the following symbolic error names: 


E2BIG 

Arg list too long 

EACCES 

Permission denied 

EAGAIN 

Resourcetemporarilyunavailable 

EBADF 

Bad file descriptor 

EBUSY 

Resource busy 

ECHILD 

N o child processes 

EDEADLK 

Resource deadlock avoided 

EDOM 

Domain error 

EEXIST 

Fileexists 

EFAULT 

Bad address 

EFBIG 

Filetoo large 

EINTR 

Interrupted function call 

EINVAL 

Invalid argument 

EIO 

Input/output error 

EISDIR 

Isa directory 

EMFILE 

Too many open files 

EMLINK 

Too many links 

ENAMETOOLONG 

Filenametoo long 

ENFILE 

Too many open files in system 

ENODEV 

N o such device 

ENOENT 

No such file or directory 

ENOEXEC 

Exec format error 

ENOLCK 

N o locks available 

ENOMEM 

N ot enough space 
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ENOSPC 

N o space left on device 

ENOSYS 

Function not implemented 

ENOTDIR 

N ot a di rectory 

ENOTEMPTY 

Directory not empty 

ENOTTY 

Inappropriate I/O control operation 

ENXIO 

N o such device or address 

EPERM 

Operation not permitted 

EPIPE 

Broken pipe 

ERANGE 

Result too large 

EROFS 

Read-only filesystem 

ESPIPE 

Invalid seek 

ESRCH 

N o such process 

EXDEV 

Improper link 

SEE ALSO 



perror(3) 

21 July 1996 

exit 

exit— Causes normal program termination 

SYNOPSIS 

#include <stdlib.h> 
void exit(int status); 

DESCRIPTION 

Theexito function causes normal program termination, and the value of status is returned to the parent. All functions 
registered with atexito and on exito are called in the reverse order of their registration, and all open streams are flushed 
and closed. 

RETURN VALUE 

Theexito function does not return. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

_exit(2), atexit(3), on_exit(3) 

GNU, 2 April 1993 


exp, log, log10, pow 

exp, log, iogi 0 , pow— Exponential, logarithmic, and power functions 

SYNOPSIS 


#include <math.h> 
double exp(double x); 



Part III: Library Functions 

double log(double *); 
double log10(double *); 
double pow(double x, double y); 

DESCRIPTION 

The expo function returnsthevalueof e (the base of natural logarithms) raised to the power of x. 

The logo function returns the natural logarithm of x. 

The iogi 0 ( ) function returnsthebase-10 logarithm ofx. 

Thepowo function returnsthevalueof x raised to the power of y. 

ERRORS 

The logo and logioo functions can return thefollowing errors 

edom The argument x is negative. 

erange The argument x iso. The log of 0 is not defined. 

Thepowo function can return thefollowing error: 

edom T he argument x is negative and y is not an integral value. This would result in a complex number. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

sqrt(3), cbrt(3) 

GNU June 16,1993 

expml,loglp 

expmi, logip— Exponential minus 1, logarithm of 1 plus argument 

SYNOPSIS 

#include <math.h> 
double expml (double x); 
double loglp (double x); 

DESCRIPTION 

expmi (x) returns a value equivalent to exp (x)-l. It is computed in away that is accurate even if the value of x is near 0— a 
case where exp (x)-l would be inaccurate due to subtraction of two numbers that are nearly equal. 

iogi p (x) returns a value equivalent to log (1 +x). It is computed in a way that is accurate a/en if the value of x is near 0. 

C0NF0RMST0 

BSD 

SEE ALSO 



exp(3), log(3) 


GNU, 16 September 1995 
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tabs 

F abs— A bso I ute val u e of f I oati n g- po i n t n um ber 

SYNOPSIS 

#include <math.h> 
double fabs(double x); 

DESCRIPTION 

T he f abs () function returns the absolute value of the floati ng-point number x . 

C0NF0RMST0 

SVID 3, PO SIX, BSD 4.3, ISO 9899 

SEE ALSO 

abs(3), ceil(3), floor(3), labs(3), rint(3) 

25Junel993 


fclose 

tciose— Closes a stream 

SYNOPSIS 

#include <stdio.h> 
int fclose(FILE *s t ream); 

DESCRIPTION 

Thetciose function dissociates the named stream from its underlying file or set of functions. If the stream was being used for 
output, any buffered data iswritten first, using ft iush(3). 

RETURN VALUES 

Upon successful completion, e isreturned. Otherwise, eof isreturned, and the global variable errno is set to indicate the 
error. I n either case, no further access to the stream is possi ble. 

ERRORS 

ebadf T he argument stream is not an open stream. 

Thetciose function may also fail and set errno for any of the errors specified for the routines ciose(2) or ttiush(3). 

SEE ALSO 

close(2), fflush(3), fopen(3), setbuf(3) 

STANDARDS 

Thetciose function conforms to AN SI C 3.159-1989 ("AN SI C"). 

BSD M an Page, 29 N ovember 1993 


clearerr,feof,ferror,fileno 

ciearerr, feof, ferror, fileno — Check and res& stream status 
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SYNOPSIS 

#include <stdio.h> 
void clearerr( FILE *s t r eam) ; 
int feof(FILE *st r earn); 
int ferror(FILE *s t ream); 
int fileno(FILE *s t ream); 

DESCRIPTION 

Thefunction ciearerr clears the end-of-file and error indicators for the stream pointed to by st r earn. 

The function feof tests the end-of-file indicator for the stream pointed to by stream, returning nonzero if it is set. The end- 
of-file indicator can only be cleared by thefunction ciearerr. 

Thefunction f error tests the error indicator for the stream pointed to by stream, returning nonzero if it is set. The error 
indicator can only be reset by the ciearerr function. 

Thefunction fiieno examines the argument stream and returns its integer descriptor. 

ERRORS 

These functions should not fail and do not set the external variable errno. 

SEE ALSO 

open(2), stdio(3) 

STANDARDS 

The functions ciearerr, feof, and f error conform to C 3.159-1989 ("ANSI C"). 

BSD M an Page, 29 N ovember 1993 


fflush,fpurge 

ffiush, fpurge — Flush a stream 

SYNOPSIS 

#include <stdio.h> 

int fflush( FILE *st r eam); 

int fpurge( FILE *st r eam); 

DESCRIPTION 

Thefunction ffiush forces a write of all buffered data for the given output or update stream via the stream's underlying write 
function. The open status of thestream is unaffected. 

If the stream argument is null, ffiush flushes all open output streams. (D oes this happen under Linux?) 

Thefunction fpurge erases any input or output buffered in the given stream. For output streams, this discards any unwritten 
output. For input streams, this discards any input read from the underlying object but not yet obtained via getc(3); this 
includes any text pushed back via ungetc. 

RETURN VALUES 

Upon successful completion, 0 is returned. Otherwise, eof is returned, and the global variableerrno is set to indicate the 
error. 

ERRORS 

ebadf Stream is not an open stream, or, in the case of ffiush, not a stream open for writing. 


Thefunction ffiush may also fail and set errno for any of the errors specified for the routine write(2). 
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BUGS 

Linux may not support fpurge. 

SEE ALSO 

write(2), fopen(3), fclose(3), setbuf(3) 

STANDARDS 

T he ffiush function conforms to AN SI C 3.159-1989 ("AN SI C"). 

BSD M an Page, 29 N ovember 1993 


ffs 

ffs— Finds first bit set in a word 

SYNOPSIS 

#include <string.h> 
int ffs(int i ); 

DESCRIPTION 

Thettso function returns the position of the first bit set in the word i. The least significant bit is position 1, and the most 
significant position 32. 

RETURN VALUE 

Thetfso function returns the position of the first bit set, or null if no bits are set. 

C0NF0RMST0 

BSD 4.3 

GNU, 13 April 1993 


fgetgrent 

tgetgrent— Gets group file entry 

SYNOPSIS 

#include <grp.h> 

#include <stdio.h> 

#include <sys/types.h> 

struct group *fgetgrent(FILE *stream); 


DESCRIPTION 

The tgetgrent o function returns a pointer to a structure containing the group information from thefi lest ream. The first 
time it is cal led it returns the first entry; thereafter, it returns successive entries. Thefi lest ream must have the same format as 
/etc/group. 

Thegroup structure is defined in <grp.h> as follows: 


struct group { 

char *gr_name; 

char *gr_passwd; 

gidt gr_gid; 

char **gr_mem; 


/* group name *1 
/* group password */ 
/* group id */ 

/* group members */ 
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RETURN VALUE 

The fgetgrent o function returnsthe group information structure or null if there are no moreentriesoran error occurs. 

ERRORS 

enomem Insufficient memory to allocate group information structure. 

CONFORMSTO 

SVID 3 


SEE ALSO 

getgrnam(3), getgrgid(3), getgrent(3), setgrent(3), endgrent(3) 


GNU, 4 April 1993 


fgetpwent 

fgetpwent— G ets password fi le entry 

SYNOPSIS 

#include <pwd.h> 

#include <stdio.h> 

#include <sys/types.h> 

struct passwd *fgetpwent(FILE *st r eam); 

DESCRIPTION 

The fgetpwent o function returns a pointer to a structure containing the broken-out fields of a line in the fi lest ream. The 
first time it is called it returns the first entry; thereafter, it returns successive entries. T he files t ream must have the same 
format as /etc/passwd. 

Thepasswd structure is defined in<pwd.h> as follows: 
struct passwd { 


char 

*pw_name; 

/* username */ 

char 

*pw_passwd; 

/* user password */ 

uid_t 

pw_uid; 

/* user id */ 

gid_t 

pw_gid; 

/* group id */ 

char 

*pw_gecos; 

/* real name */ 

char 

*pw_dir; 

/* home directory * 

char 

*pw_shell; 

/* shell program */ 


}; 

RETURN VALUE 

The fgetpwent o function returnsthe passwd structure, or null if there are no moreentriesoran error occurs. 

ERRORS 

enomem Insufficient memoryto allocate passwd structure. 

FILES 

/etc/passwd password database file 


CONFORMSTO 

SVID 3 



fmod 



SEE ALSO 

getpwnam(3), getpwuid(3), getpwent(3), setpwent(3), endpwent(3), getpw(3), putpwentf 3), passwd(5) 


GNU, 17 May 1996 


floor 

floor— Largest integral value not greater than x 

SYNOPSIS 

#include <math.h> 
double floor(double x); 

DESCRIPTION 

Thetiooro function rounds* downward to the nearest integer, returning that value as a double. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

abs(3), fabs(3), ceil(3), rint(3) 

6 Junel993 


fmod 

fmod— Floating-point remainder function 

SYNOPSIS 

#include <math.h> 

double fmod(double x, double y); 

DESCRIPTION 

T he modf () function computes the remainder of dividing* by y. The return value is x-n*y, where/i isthe quotient of x/y, 
rounded toward 0 to an integer. 

RETURN VALUE 

T he fmod o function returns the remainder unless y isO, in which case the function fails and errno is set. 

ERRORS 

edom The denominator y isO. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

drem(3) 

6 Junel993 
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fnmatch 

fnmatch— M atches filename or pathname 

SYNOPSIS 

#include <fnmatch.h> 

int fnmatch(const char ^pattern, const char *strings,int flags); 

DESCRIPTION 

fnmatch o checks thes t r i ngs argument and checks whether it matches the pat tern argument, which is a shell wildcard 
pattern. 

T he f i ags argument modifies the behavior; it is the bitwise or of zero or more of the following flags: 
fnm_noescape If this flag is set, treat backslash as an ordinary character instead of as an escape character. 

fnm_pathname If this flag is set, match a slash in stri ng only with a slash in pattern and not, for example, with 

an - sequence containing a slash. 

fnm_period If this flag isset, a leading period in stri ng has to be matched exactly by a period in pattern. A 

period is considered to be leading if it isthefi rst character in stri ng, or if both fnm_pathname is 
set and the period immediately follows a slash. 

RETURN VALUE 

Zero if st r i ng matches pat t er n, fnmjjomatch if there is no match, or another value if there is an error. 

C0NF0RMST0 

Proposed POSIX.2 

BUGS 

POSIX.2 is not yet an approved standard; the information in this man page is subject to change. 

SEE ALSO 

sh( 1), glob(3), glob(7) 

GNU, 19 April 1993 



f open, f dopen, f reopen 

fopen, fdopen, freopen —Stream open functions 

SYNOPSIS 

#include <stdio.h> 

FILE *fopen( char *pat h , char *mode); 

FILE *fdopen( int fildes, char * mo d e); 

FILE *freopen( char *pat h , char *mode,FILE*strearn); 

DESCRIPTION 

Thetopen function opensthefile whose name isthe string pointed to bypath and associates a stream with it. 

The argument mode points to a string beginning with one of the following sequences (additional characters may follow these 
sequences): 


r+ 


Open text file for reading. The stream is positioned at the beginning of the file. 
Open for reading and writing. The stream is positioned at the beginning of the file. 



fpathconf, pathconf 



w T runcatefileto zero length or create a text file for writing. The stream is positioned at the 

beginning of thefile 

w+ Open for reading and writing. The file is created if it does not exist; otherwise it is truncated. 

The stream is positioned at the beginning of thefile. 

a Open for writing. The file is created if it does not exist. The stream is positioned at the end of 

thefile. 

a+ Open for reading and writing. T hefile iscreated if it does not exist. The stream is positioned at 

the end of thefile. 

The mode string can also include the letter b either as a third character or as a character between the characters in any of the 
two-character strings described previously. T his is strictly for compatibility with AN SI C 3.159-1989 (AN SI C) and has no 
effect; the b is ignored. 

Any created files will have modes_iRusR|s_iwusR|s_iRGRP|s_iwGRP|s_iROTH|s_iwoTH (0666), as modified by the process's 
umask value. (See umask(2).) 

Reads and writes may be intermixed on read/write streams in any order. N otethat AN SI C requires that a file positioning 
function intervene between output and input, unless an input operation encounters end-of-file. (If thiscondition isnot met, 
then a read is allowed to return the result of writes other than the most recent.) Therefore it is good practice (and indeed 
sometimes necessary under Linux) to put an tseek or tgetpos operation between write and read operations on such a stream. 
This operation may bean apparent no-op (as in t seek(..., gl, seek_curj ) called for its synchronizing side effect. 

Thetdopen function associates a stream with the existing file descriptor, tildes. The mode of the stream must be compatible 
with the mode of the file descriptor. The file descriptor isnot duplicated. 

Thetreopen function opens thefilewhosenameisthe string pointed to by path and associates the stream pointed to by 
stream with it. T he original stream (if it exists) is closed. The mode argument is used just as in the f open function. The 
primary use of thetreopen function is to change the file associated with a standard text stream (stderr, stdin, or stdout). 

RETURN VALUES 

On successful completion, topen, tdopen, and treopen return a file pointer. Otherwise, null is returned, and the global 
variableermo i s set to indicate the error. 

ERRORS 

einval The mode provided to topen, tdopen, or treopen was invalid. 

The topen, tdopen, and treopen functions may also fail and set errno for any of the errors specified for the routine maiioc(3). 
The topen function may also fail and set errno for any of the errors specified for the routine open(2). 

Thetdopen function may also fail and set errno for any of the errors specified for the routine tcnti(2). 

Thetreopen function may also fail and set errno for any of the errors specified for the routines open(2), tciose(3) and 
fflush(3). 

SEE ALSO 

open(2), fclose(3) 

STANDARDS 

The topen and treopen functions conform to AN SI C 3.159-1989 (AN SI C). Thetdopen function conforms to IEEE 
Stdl003.1-1988 (POSIX.1). 

BSD M an Page, 13 December 1995 


fpathconf, pathconf 

tpathcont, pathconf— Get configuration values for files 
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SYNOPSIS 

#include <unistd.h> 

long fpathconf(int fiIedes,intna me); 

long pathconf(char *p a t h, int name); 


DESCRIPTION 


fpathconf o gets a value for the configuration option name for the open fi le descriptor f i i edes. 
pathconf o gets a value for configuration option name for thefilename path. 

The corresponding macros defined in <unistd.h> are the minimum values; if an application wants to take advantage of values 
that may change, a call to fpathconf o or pathconf o can be made, which may yield more liberal results. 


Setting name equal to one of the following constants returnsthefollowing configuration options: 


PC_LINK_MAX 

PC_MAX_CANON 

PC_MAX_INPUT 

PC_NAME_MAX 

PC PATH_MAX 

PC_PIPE_BUF 

PC_CHOWN_RESTRICTED 

PC_NO_TRUNC 

PC_VDISABLE 


Returns the maxi mum number of links to the file. If f i i edes or path refers to a directory, the 
value applies to the whole directory. The corresponding macro is_Posix_LiNK_MAx. 

Returns the maximum length of a formatted input line, where f i edes or path must refer to a 
terminal. The corresponding macro is_Posix_MAx_cANON. 

Returns the maximum length of an input line; wheret i i edes or path must refer to a terminal. 
The corresponding macro is_posix_MAx_iNPUT. 

Returns the maximum length of a filename in the directory path or fiiedes the process is 
allowed to create. The corresponding macro is_Posix_MAx_. 

Returns the maximum length of a relative path name when path or f i i edes isthe current 
working directory. The corresponding macro is_posixj 5 ATHjiAx. 

Returns the size of the pipe buffer, wheret i i edes must refer to a pipe or FIFO, and path must 
refer to a FIFO. The corresponding macro is_Posix pipe_buf. 

Returns nonzero if the chown(2) call may not be used on thisfile. If t i i edes or path refers to a 
directory, this applies to all files in that directory. The corresponding macro is 

_POSIX_CHOWN_RESTRICTED. 

Returns nonzero if accessing filenames longer than _posixjjame_max generates an error. T he 
corresponding macro is_Posix_No_TRUNC. 

Returns nonzero if special character processi ng can be disabled, where f i i edes or path must 
refer to a terminal. 


RETURN VALUE 

The limit is returned, if one exists. If the system does not have a limit for the requested resource, -i is returned, and enrno is 
unchanged. If thereisan error, -i is returned, and errno i s set to reflect the nature of the error. 

C0NF0RMST0 

POSIX.1. Files with name lengths longer than the value returned forname equal to pc_name_max may exist in thegiven 
directory. 

Some returned values may be huge; they are not suitable for allocating memory. 

SEE ALSO 

getconf(1), statfs(2), open(2), sysconf(3) 

GNU, 4 April 1993 


tread, fwrite 

tread, fwrite— Binary stream input/output 
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SYNOPSIS 

#include <stdio.h> 

size_t fread(void *ptr, size_t size, size_t nmemb ,FILE*st ream); 
size_t fwrite(void *ptr, size_t size, size_t nmemb ,FILE*st ream); 

DESCRIPTION 

Thefunction tread reads n me mb elements of data, each size bytes long, from thestream pointed to bystream, storing them at 
the location given by pt r. 

Thefunction twrite writesnmemb elements of data, each size bytes long, to thestream pointed to bystream, obtaining them 
from the location given by pt r. 

RETURN VALUES 

tread and twrite return the number of items successfully read or written (that is, not the number of characters). If an error 
occurs, or the end-of-file is reached, the return value is a short item count (or 0 ). 

tread does not disti nguish between end-of-file and error, and callers must useteot(3) and terror(3) to determine which 
occurred. 

SEE ALSO 

feof(3), ferror(3), read(2), write(2) 

STANDARDS 

The functions tread and twrite conform to AN SI C 3.159-1989 ("AN SI C"). 

BSD M an Page, 17 M ay 1996 


frexp 

trexp— Converts floating-point number to fractional and integral components 

SYNOPSIS 

#include <math.h> 

double frexp(double x, int *exp); 

DESCRIPTION 

The trexp 0 function is used to split the number x into a normalized fraction and an exponent that is stored in exp. 

RETURN VALUE 

Thetrexpo function returns the normalized fraction. If the argument x is note, the normalized fraction isx timesapower 
of 2, and is always in the ranged (inclusive) to 1 (exclusive). If x is 0 , the normalized fraction isO, and 0 is stored in exp. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

ldexp(3), modf(3) 

GNU, 6Junel993 


fgetpos, fseek, fsetpos, ftell, rewind 

fgetpos, fseek, fsetpos, fteii, rewind — Reposition a stream 



Part III: Library Functions 



SYNOPSIS 

#include <stdio.h> 

int fseek(FILE *s t r e a m , longo ffset , int whence); 

long ftell(FILE *st r eam); 

void rewind(FILE *st r eam); 

int fgetpos(FILE *s tream, fpos_t *pos); 

int fsetpos(FILE *s t r e a m , fpos_t *pos); 

DESCRIPTION 

T he f seek function sets the file position indicator for the stream pointed to by stream. The new position, measured in bytes, 
is obtained by adding offset bytes to the position specified by whence. If whence is set to seek_set, seek_cur, or seekend, the 
offset is relative to the start of the file, the current position indicator, or end-of-file, respectively. A successful call to the f seek 
function clears the end-of-file indicator for the stream and undoes any effects of the ungetc(3) function on the same stream. 

T he f ten function obtains the current value of the file position indicator for the stream pointed to by stream. 

The rewind function sets the file position indicator for the stream pointed to by s t r ea m to the beginning of thefile. Itis 
equivalent to 

(void)fseek(strean, 0L, SEEK_SET); 

except that the error indicator for the stream is also cleared. (Seeciearerr(3).) 

Thetgetpos and tsetpos functions are alternate interfaces equivalent to tteii and fseek (with whence set to seek_set), setting 
and storing the current value of the file offset into or from the object referenced by pos . On some non-U N IX systems, an 
fpos_t object may be a complex object, and these routines might be the only way to portably reposition a text stream. 

RETURN VALUES 

The rewind function returns no value. Upon successful completion, tgetpos, fseek, and tsetpos return 0 , and tteii returns 
thecurrent offset. Otherwise, -1 is returned, and the global variableerrno is set to indicate the error. 

ERRORS 

ebadf T he stream specified is not a seekable stream. 

einval The whence argument to fseek was not seek_set, seek_end, orsEEK_cuR. 

The function tgetpos, fseek, tsetpos, and tteii might also fail and set errno for any of the errors specified for the routines 
ftlush(3), fstat(2), lseek(2), and malloc(3). 

SEE ALSO 

lseek(2) 

STANDARDS 

Thetgetpos, tsetpos, fseek, tteii, and rewind functions conform to AN SI C 3.159-1989 (ANSI C). 

BSD M an Page, 29 N ovember 1993 


f time 

ttime— Returns date and time 

SYNOPSIS 


#include <sys/timeb.h> 
int ftime(struct timeb *tp); 



ftok 


929 


DESCRIPTION 

Return current date and time in tp, which is declared as follows: 

struct timeb { 
time_t time; 
unsigned short millitm; 
short timezone; 
short dstflag; 

}; 

RETURN VALUE 

T his function always returns 0 . 

NOTES 

Under Linux, thisfunction is implemented in a compatibility library instead of in the kernel. 

C0NF0RMST0 

Version 7, BSD 4.3 

Under BSD 4.3, thiscall isobsoleted by gettimeofday(2). 

SEE ALSO 

time(2) 

Linux, 24July 1993 


ftok 

ftok— Converts a pathname and a project identifier to a System V I PC key 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/ipc.h> 

key_t ftok (char ‘pathname, char p roj ); 

DESCRIPTION 

The function converts the pathname of an existing accessible file and a project identifier into a key_t type System V I PC key. 

RETURN VALUE 

On success, the return value will be the converted key_t value; otherwise it will be- 1 , with errno indicating theerror as for 
the stat(2) system call. 

BUGS 

Thegenerated key_t value is obtained by stating the disk file corresponding to pathname in order to get its i-node number 
and the minor device number of the filesystem on which the disk file resides, then by combining the 8-bit proj value along 
with the lower 16 bits of the inode number with the 8 bits of the minor device number. The algorithm does not guaranteea 
unique key value. In fact, 

■ Two different names I inking to the same file produce the same key values. 

■ Using the lower 16 bits of the i-node number gives some chance (although usually small) to have the same key values 
for filenames referring to different inodes. 

■ N ot discriminating among major device numbers gives some chance of collision (also usually small) for systems with 
multiple disk controllers. 
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SEE ALSO 

ipc(5), msgget(2), semget(2), shmget(2), stat(2) 


Linux 0.99.13,1 N ovember 1993 


ftw 

ftw— File tree walk 

SYNOPSIS 

#include <ftw.h> 

int ftw(const char *di rectory, 

int(*f uncpt r ) (const char *f i I e, struct stat *s b, int flag), int depth); 

DESCRIPTION 

ftw () walks through the directory tree, starting from the i ndicated d i rectory. For each found entry in the tree, it calls f uncpt r 
with the full pathname of the entry relative to d i rectory, a pointer to the stat(2) structure for the entry and an int whose 
value will be one of thefollowing: 


FTW_F 

Item is a normal file 

FTW_D 

Item isa directory 

FTW_NS 

The stat failed on the item 

FTW_DNR 

Item isa directory which can't be read 


Warning: Anything other than directories, such as symbolic links gets the ftw_f tag. 

ftw () recursively calls itself for traversing found directories. T o avoid using up all a program's file descriptors, depth specifies 
the number of simultaneous open directories. When the depth is exceeded, ftwo will become slower because directories have 
to be closed and reopened. 

T o stop the tree walk, t uncpt r returns a nonzero value; this value will become the return value of ftpo. Otherwise, ftwo will 
continue until it has traversed the entire tree (in which case it will return 0 ), or until it hits an error such asamaiioc(3) 
failure, in which case it will return - 1 . 

Because ftp 0 uses dynamic data structures, the only Safeway to exit a tree walk is to return a nonzero value. T 0 handle 
interrupts for example, mark that the interrupt occurred and return anonzero value—don't useiongjmp(3) unless the 
program is going to terminate. 

SEE ALSO 

stat(2) 

Linux, 18 July 1993 


gcvt 

gcvt — C onverts a floating-point number to a string 

SYNOPSIS 

#include <stdlib.h> 

char *gcvt(double number , size_t ndigit, char *buf); 

DESCRIPTION 

T he gcvt 0 function converts number to a minimal-length, N U LL-terminated ASCII string and stores the result in b uf . It 
produces ndi gi t significant digits in either printf 0 F format or E format. 



getdiren tries 
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RETURN VALUE 

Thegcvto function returns the address of the string pointed to by but. 

SEE ALSO 

ecvt(3), fcvt(3), sprintf(3) 

29 March 1993 


getcwd, get_current_dir_name,getwd 

getcwd, get_current_dir_name, getwd—Get current working directory 

SYNOPSIS 

#include <unistd.h> 
char *getcwd(char *buf , size_t size); 
char *get_current_working_dir_name(void); 
char *getwd(char *buf); 


DESCRIPTION 

The getcwd o function copies the absolute pathname of the current working directory to the array pointed to by buf , which is 
of length si ze. 

If the current absolute path name would require a buffer longer than si ze elements, null is returned, and errno is set to 
erange; an application should check for thiserror, and allocate a larger buffer if necessary. 

As an extension to thePOSIX.1 standard, getcwd o allocates the buffer dynamically using maiioco if but is null on call. In 
this case, the allocated buffer has the length si ze unless size is I ess than 0, when buf is allocated as large as necessary. It is 
possi ble (and, indeed, advisable) to free the buffers if they have been obtained thisway. 

get_current_dir_nai»e, which is only prototyped if_ use_gnu isdefined, will maiioc(3) an array big enough to hold the 

current directory name. If the environment variable pwd is set, and its value is correct, that value will be returned. 

getwd, which is only prototyped if_ use_bsd isdefined, will not maiioc(3) any memory. The buf argument should be a 

pointer to an array at least path_max bytes long, getwd returns only the first path_max bytes of the actual pathname. 

RETURN VALUE 

null on failure (for example, if the current directory is not readable), with errno set accordingly, and buf on success. 

C0NF0RMST0 

POSIX.1 


SEE ALSO 

chdir(2), free(3), malloc(3). 


GNU, 21]ulyl993 


getdirentries 

getdirentries— Gets directory entries in a filesystem-independent format 

SYNOPSIS 

#define _USE_BSD or #define _USE_MISC 
#include <dirent.h> 

ssize_t getdirentries(int fd, char *buf , size_t nbytes ,offt *basep); 
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DESCRIPTION 

This function reads directory entries from the directory specified by f d into but . At most, nbytes are read. Reading starts at 
offset *basep , and *basep is updated with the new position after reading. 

RETURN VALUE 

getdirentries returns the number of bytes read, or 0 when at the end of the directory. If an error occurs, -1 is returned, and 
errno is set appropriately. 

ERRORS 

Seethe Linux library source code for details. 

SEE ALSO 

open(2), lseek(2) 

BSD/M ISC, 22 July 1993 


getenv 

getenv— Getsan environment variable 

SYNOPSIS 

#include <stdlib.h> 

char *getenv(const char *na me); 

DESCRIPTION 

The getenv 0 function searches the environment list for a string that matches the string pointed to byname. The strings are of 
theform n a me =v a I ue. 

RETURN VALUE 

The getenv 0 function returns a pointer to the value in the environment, or null if there is no match. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

putenv(3), setenv(3), unsetenv(3) 

GNU, 3 April 1993 


getgrent, setgrent,endgrent 

getgrent, setgrent, endgrent— G et group fi le entry 


SYNOPSIS 

#include <grp.h> 

#include <sys/types.h> 
struct group *getgrent(void); 
void setgrent(void); 
void endgrent(void); 



getgrnam, getgrgid 



DESCRIPTION 

Thegetgrento function returns a pointer to a structure containing the group information from /etc/group. The first time it 
is called it returns the first entry; thereafter, it returns successive entries. 

Thesetgrento function rewinds the fi le pointer to the beginning of the/etc/group file. 

TheendgrentO function Closes the/etc/group file. 

Thegroup structure is defined in <grp.h> as follows: 


struct group { 

char *gr_name; 

char *gr_passwd; 

gid_t gr_gid; 

char **gr_mem; 


/* group name */ 

/* group password */ 
/* group id */ 

/* group members */ 


RETURN VALUE 

The getgrent ((function returns the group information structure, or null ifthereareno more entries or an error occurs 


ERRORS 

enomem Insufficient memory to allocate group information structure. 


FILES 

/etc/group group database file 

C0NF0RMST0 

SVID 3, BSD 4.3 

SEE ALSO 

fgetgrent(3), getgrnam(3), getgrgid(3) 

GNU, 4 April 1993 


getgrnam,getgrgid 

getgrnam, getgrgid— Get group fi le entry 

SYNOPSIS 

#include <grp.h> 

#include <sys/types.h> 

struct group *getgrnam(const char *na me); 

struct group *getgrgid(gid_t gid); 

DESCRIPTION 

The getgrnam o function returns a pointer to a structure containing thegroup information from /etc/group for the entry that 
matches the group name name. 

The getgrgido function returns a pointer to a structure containing thegroup information from /etc/group for the entry that 
matches the group id gi d. 

Thegroup structure is defined in <grp.h> as follows: 
struct group { 

char *gr_name; /* group name */ 

char *gr_passwd; /* group password */ 
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gidt gr_gid; /* group id */ 

char **gr_mem; /* group members */ 

}; 

RETURN VALUE 

T he getgrnam( >and getgrgido functions return the group information structure, or null if the matching entry is not found 
or an error occurs. 

ERRORS 

enomem Insufficient memory to allocate group information structure. 

FILES 

/etc/group group database file 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3 

SEE ALSO 

fgetgrent(3), getgrent(3), setgrent(3), endgrent(3) 

GNU, 4 April 1993 



getlogin,cuserid 

getlogin, cuserid— G et username 

SYNOPSIS 

#include <unistd.h> 
char * getlogin ( void ); 

#include <stdio.h> 

char * cuserid ( char *string ); 

DESCRIPTION 

getlogin returns a pointer to a string containing the name of the user logged in on the controlling terminal of the process, or 
a null pointer if this information cannot be determined. The string is statically allocated and might be overwritten on 
subsequent calls to thisfunction or to cuserid. 

cuserid returnsa pointer to a string containing a username associated with the effective user ID of the process. Ifstring is 
not a null pointer, it should bean array that can hold at least L_cuserid characters; thestring is returned in thisarray. 
Otherwise, a pointer to a string in a static area is returned. This string isstati cally allocated and might be overwritten on 
subsequent calls to thisfunction or to getlogin. 

The macro L_cuserid is an integer constant that indicates how long an array you might need to store a username. L_cuserid is 
declared in stdio.h. 

These functions let your program positively identify the user who is running (cuserid) or the user who logged in this session 
(getlogin). (These can differ when setuid programs are involved.) The user cannot do anything to fool these functions. 

For most purposes, it is more useful to use the environment variable logname to find out who the user is. This is more flexible 
precisely because the user can set logname arbitrarily. 

ERRORS 


ENOMEM 


Insufficient memory to allocate passwd structure 



getmntent, setmntent, addmntent, endmntent, hasrmtopt 

FILES 

The /etc/passwd password database file /etc/utmp (or /var/adm/utmp, or wherever your utmp file lives these days— the proper 
location depends on your libc version) 

C0NF0RMST0 

POSIX.1. System V hasacuserid function that uses the real user ID rather than the effective user ID. Thecuserid function 
was included in the 1988 version of PO SIX, but was removed from the 1990 version. 

BUGS 

Unfortunately, it is often rather easy to fool getiogino. Sometimes it does not work at all, because some program messed up 
the utmp file Often, it gives only thefirst eight characters of the login name. The user currently logged in on the controlling 
tty of your program need not be the user who started it. 

Nobody knows precisely what cuserido does; so 

■ Avoid it in portable programs 

■ Avoid it altogether 

■ U se getpwuid (geteuido) instead, if that is what you meant. 

Simply, do not usecuserido. 

SEE ALSO 

geteuid(2), getuid(2) 

L inux 1.2.13, 3 September 1995 

getmntent, setmntent, addmntent, endmntent, hasmntopt 

getmntent, setmntent, addmntent, endmntent, hasmntopt—G Gt filesyStem descriptor file entry 

SYNOPSIS 

#include <stdio.h> 

#include <mntent.h> 

FILE *setmntent(const char *filep, const char *type); 
struct mntent *getmntent (FILE *filep); 
int addmntent (FILE *filep, const struct mntent *mnt); 
int endmntent (FILE *fiIep); 

char *hasmntopt(const struct mntent *mnt , const char *opt); 

DESCRIPTION 

These routines are used to access the filesystem description file /etc/f stab and the mounted filesystem description file/etc/ 
mstab. 

The setmntent o function opens the filesystem description filef i i ep and returns a file pointer that can be used by 
getmntent o. The argument type isthetypeof access required and can take the same values as the mode argument of fopen(3). 

The getmntent o function reads the next line from the filesystem description filet 1 1 ep and returns a pointer to a structure 
containing the broken-out fields from a line in the file The pointer points to astatic area of memory that is overwritten by 
subsequent calls to getmntent(). 

T he addmntent! ) function adds the mntent structure mnt to theend of theopen filefilep. 

T he endmntent) ) function doses the filesystem description filet i i ep. 

The hasmntopt o function scans the mnt _opts field of the mntent structure mnt for a substring that matches opt. (See 
<mntent.h> for valid mount options.) 
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T he mntent structure is defined in <mntent.h> asfollows: 
struct mntent { 


char 

*mnt_fsname; 

/* name of mounted filesystem */ 

char 

*mnt_dir; 

/* filesystem path prefix */ 

char 

*mnt_type; 

/* mount type (see mntent.h) */ 

char 

*mnt_opts; 

/* mount options (see mntent.h) * 

int 

mnt_freq; 

/* dump frequency in days */ 

int 

mnt_passno; 

/* pass number on parallel fsck * 


}; 

RETURN VALUE 

T he getmntent () function returns a pointer to the mntent structure or null on failure. 

T he addmntent() function returns© on success and i on failure. 

The endmntent() functionsalways returns i. 

The hasmntopt () function returns the address of thesubstring if amatch isfound, and null otherwise. 

FILES 

/etc/fstab filesystem description file 
/etc/mtab mounted filesystem description file 

C0NF0RMST0 

BSD 4.3 

SEE ALSO 

fopen(3), fstab(5) 
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getnetent,getnetbyaddr,getnetbyname,setnetent,endnetent 

getnetent, getnetbyaddr, getnetbyname, setnetent, endnetent— Get network entry 

SYNTAX 

#include <netdb.h> 
struct netent ‘getnetent() 
struct netent *getnetbyname(name) 
char ‘name; 

struct netent *getnetbyaddr(net , type) 

long net ; int type; 

void setnetent(st ayopen) 

int st ayopen; 

void endnetent)) 

DESCRIPTION 

The getnetent, getnetbyname, and getnetbyaddr subrouti nes each return a pointer to an object with the foil owing structure 
containing the broken-out fields of a line in the network database, /etc/networks: 

struct netent { 


char 

*n_name; 

/* official name of net 

char 

“n_aliases; 

/* alias list */ 

int 

n_addrtype; 

/* net number type */ 

long 

n_net; 

/* net number */ 


}; 
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T he members of this structure are 

n_name The official name of the network. 

n_aiiases A zero-terminated list of alternate names for the network. 

n_addrtype T he type of the network number returned: af_inet. 

n_net The network number. Network numbers are returned in machine byte order. 

If the st ay open flag on asetnetent subroutine is null, the network database is opened. Otherwise the setnetent has the effect 
of rewi ndi ng the network database. The endnetent may be cal led to close the network database when processi ng is complete. 

Thegetnetent subroutine simply reads thenext line whereas getnetbyname and getnetbyaddr search until a rnatchingname or 
net number is found (or until eof is encountered). The type must be af_inet. Thegetnetent subroutine keeps a pointer in 
thedatabase, allowing successive calls to beused to search the entire file. 

A call to setnetent must be made before a while loop using getnetent to perform initialization, and an endnetent must be 
used after the loop. Both getnetbyname and getnetbyaddr makecallsto setnetent and endnetent. 

FILES 

/etc/networks 

DIAGNOSTICS 

N ull pointer ( 0 ) returned on eof or error. 

SEE ALSO 

networks(5), RFC 1101 

HISTORY 

T hegetnetent(), getnetbyaddr)), getnetbyname)), setnetent)), and endnetent) ) functions appeared in 4.2BSD . 

BUGS 

Thedata space used by these functions is static; if future use requires the data, it should be copied before any subsequent calls 
to these functions overwrite it. Only Internet network numbers are currently understood. Expecting network numbers to fit 
in no more than 32 bits is probably naive. 

getopt 

getopt— Parses command-line options 

SYNOPSIS 

#include <unistd.h> 

int getopt(int argc, char * const a r g v[] , 
const char *opt st r i ng) ; 
extern char *o pt a r g ; 
extern int optind, opterr, optopt; 

#include <getopt.h> 

int getopt_long(int argc, char * const arg v[] , 
const char *optstri ng , 

const struct option *1 ongopts , int *1 ongi ndex ); 
int getopt_long_only(int argc, char * const a r g v[] , 



const char *opt st ri ng , 

const struct option *1 ongopts, int *1 ongi ndex); 
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DESCRIPTION 

Thegetopto function parses the command-line arguments. Itsargumentsargc andargv are the argument count and array as 
passed to the main o function on program invocation. An element of argv that starts with - (and is not exactly - or --) is an 
option element. T he characters of this element (asidefrom the initial -) are option characters. If getopto iscalled repeatedly, 
it returns successively each of the option characters from each of the option elements. 

If getopto finds another option character, it returns that character, updating the external variable opti nd and a static variable 
next char so that the next call to getopto can resume the scan with the following option character or argv element. 

If there are no more option characters, getopto returns eof. Then optind istheindex in argv of thefirstargv element that is 
not an option. 

opt st r i ng is a string containing the legitimate option characters. If such a character is followed by a colon, the option 
requires an argument, so getopt pi aces a pointer to the following text in the same argv element, or the text of the following 
argv element, in opt a rg. Two colons mean an option takes an optional arg; if there is text in the current argv element, it is 
returned in optarg; otherwise, optarg is set to 0 . 

By default, getargso permutes the contents of a r gv as it scans, so that a/entually all the non-options are at the end. T wo 
other modes are also implemented. If the first character of optstring is + or the envi ronment variable posixly_correct is set, 
option processing stops as soon asa non-option argument is encountered. If thefirst character of optstring is-, each non- 
option argv element is handled as if it were the argument of an option with character code 1. (Thisisused by programsthat 
were written to expect options and other argv elements in any order and that care about the ordering of the two.) The special 
argument - forces an end of option-scanning regardless of the scanning mode. 

If getopto does not recognize an option character, it prints an error message to stderr, stores the character in optopt, and 
returns?. T he calling program may prevent the error message by setting opterr to 0 . 

T he getopt_iong( (function works like getopto, except that it also accepts long options, started out by two dashes. Long 
option names may be abbreviated if the abbreviation is unique or is an exact match for some defined option. A long option 
may take a parameter, oftheforrn--arg=paramor--arg param. 

1 ongopt s is a pointer to thefirst element of an array of struct option declared in <getopt.h>: 

as struct option { 
const char *name; 
int h a s _ a r g ; 
int *f I a g ; 
int val ; 

}; 

The meanings of the different fields are 

name T he name of the long option. 

h a s _ a r g no_argument (or 0 ) if the option does not take an argument, required_argument (or 1 ) if the 

option requires an argument, or optionai_argument (or 2 ) if the option takes an optional 
argument. 

flag Specifies how results are returned for a long option. If f 1 a g isNun, getopt _iongo returns v a 1 . 

(For example the calling program might set vai to the equivalent short option character.) 
Otherwise, getopt_iong() returns 0 , and flag points to a variable that is set to v a 1 iftheoption 
isfound, but left unchanged iftheoption is not found, 
vai Thevalueto return or to load into the variable pointed to by f 1 a g. 

The last element of the array has to be filled with zeroes. 

If 1 ongi ndex is not null, it points to a variable that is set to the index of the long option relative to 1 ongopt s. 

getopt_iong_oniy( ) is like getopt_iong< ), but - as well as -- can indicate a long option. If an option that starts with - (not --) 
doesn't match a long option but does match a short option, it is parsed asa short option instead. 
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RETURN VALUE 

The getopt ((function returns the option character if the option was found successfully, : if there was a missing parameter for 
one of the options ? for an unknown option character, or eof for the end of the option list. 

getopt_iong () and getopt_iong_oniy() also return the option character when a short option is recognized. For a long option, 
they return va i if f i a g is null, and 0 otherwise. Error and eof returns are the same as for getopt 0 , plus? for an ambiguous 
match or an extraneous parameter. 

ENVIRONMENT VARIABLES 

posixly_correct If this is set, option processing stops as soon as a non-option argument is encountered. 

EXAMPLE 

T he following example program, from thesourcecode illustrates the use of getopt_iong() with most of its features: 

#include <stdio.h> 
int 

main (a r gc, a r g v) 
int a r gc ; 
char **a rgv; 

{ 

int c ; 

int di gi t_opt i nd = 0; 
while (1) 

{ 

int this_option_optind = optind ? optind : 1; 

int option _index = 0; 

static struct option I ong_options[ ] = 

{ 

{"add", 1, 0, 0}, 

{"append", 0, 0, 0>, 

{"delete", 1, 0, 0>, 

{"verbose", 0, 0, 0}, 

{"create", 1, 0, 'c'}, 

{"file", 1, 0, 0g, f0, 0, 0, 0} 

}; 

c = getopt_long (argc, argv, "abc:d:012", 

I ongopti ons, &option_index); 
if (c == -1) 
break; 
switchfc) 

{ 

case 0: 

printf ("option %s", I ong_options[option J ndex]. name ); 
if (o p t a r g) 

printf (" with arg %s", optarg); 
printf ("\n"); 
break; 
case 1 0 1 : 
case '1': 
case '2': 

if (di gi t_opti nd ! = 0 && di gi topti nd != thi s_opti on_opti nd) 
printf ("digits occur in two different argv-elements.\n"); 
di git opti nd = thi s opti on_opti nd; 
printf ("option %c\n", c); 
break; 
case 1 a 1 : 

printf ("option a\n"); 
break; 
case 'b 1 : 
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printf ("option b\n"); 
break; 
case 'o': 

printf ("option c with value '%s'\n“, o p t a r g); 
break; 
case 'd 1 : 

printf ("option d with value '%s' \n", optarg); 
break; 
case 
break; 
default: 

printf ("?? getopt returned character code 0%o ??\n", c); 

} 

} 

if (opti nd < ar gc ) 

{ 

printf ("non-option ARGV-elements: "); 
while (opt i nd < a r g c) 
printf ("%s ", argv[opti nd++] ); 
printf ("\n"); 

} 

exit (0); 

} 

BUGS 

This man page is confusing. 

C0NF0RMST0 

getopto: POSIX.1, provided the environment variable posixly_correct is set. Otherwise the elements of argv aren't 

really const, because they get permuted. They're set const in the prototype to be compatible with other 
systems. 

GNU, 30 August 1995 

getpass 

getpass— G eis a password 

SYNOPSIS 

#include <pwd.h> 

#include <unistd.h> 

char ‘getpass( const char * prompt ); 

DESCRIPTION 

The getpass function displays a prompt to, and reads in, a password from, /dev/tty. If this file is not accessible, getpass 
displaystheprompt on the standard error output and reads from the standard input. 

The password may beupto_PAsswoRD_LEN (currently 128) characters in length. Any additional characters and the terminat¬ 
ing newline character are discarded. (This might be different in Linux.) 

getpass turns off character echoing while reading the password. 

RETURN VALUES 

getpass returns a pointer to the null-terminated password. 
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941 


FILES 

/dev/tty 

SEE ALSO 

crypt(3) 

HISTORY 

A getpass function appeared in Version 7 AT&T UNIX. 

BUGS 

The getpass function leaves its result in an internal static object and returns a pointer to that object. Subsequent calls to 
getpass will modify the same object. 

The calling process should zero the password as soon as possible to avoid leaving the cleartext password visible in the 
process's address space. 

BSD M an Page29 N ovember 1993 

getprotoent, getprotobyname, getprotobynumber,setprotoent, 
endprotoent 

getprotoent, getprotobyname, getprotobynumber, setprotoent, endprotoent— Get protocol entry 

SYNOPSIS 

#include <netdb.h> 

struct protoent *getprotoent(void); 

struct protoent *getprotobyname(const char *name); 

struct protoent *getprotobynumber(int proto); 

void setprotoentfint st ayopen); 

void endprotoent(void); 

DESCRIPTION 

The getprotoento function reads the next line from thefile/etc/protocois and returns a structure protoent containing the 
broken-out fields from the line. T he /etc/protocols file is opened if necessary. 

The getprotobyname!) function returns a pr ot oent structure for the li ne from /etc/protocois that matches the protocol name 
name. 

Thegetprotobynumbero function returns a pr ot oent structure for the line that matches the protocol number number. 

The setprotoent!) function opens and rewinds the /etc/protocols file If stay open istrue(i), thefilewill not be closed 
between calls to getprotobyname!) Or getprotobynumber!). 

The endprotoent!) function Closes /etc/protocols. 

The protoent structure is defined in <netdb.h> as follows: 
struct protoent { 

chan *p_name; /* official protocol name */ 

char **p_aliases; /* alias list */ 

int p_proto; /* protocol number */ 

} 
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T he members of the protoent structure are 

p_name The official name of the protocol. 

p_aiiases A zero-terminated list of alternative names for the protocol. 

p_proto The protocol number. 

RETURN VALUE 

The get protoent (), getprotobyname( ), and get protobynumber () functions return theprot oent structure, or a null pointer if an 
error occurs or the end of the fi le is reached. 

FILES 

/etc/protocois protocol database file 

C0NF0RMST0 

BSD 4.3 



SEE ALSO 

getservent(3), getnetent(3), protocols(5) 


BSD, 24 April 1993 


getpw 

getpw— Reconstructs password line entry 

SYNOPSIS 

#include <pwd.h> 

#include <sys/types.h> 

int getpw(uid_t uid, char *buf); 

DESCRIPTION 

Thegetpwo function reconstructs the password line entry for the given user UID uid in the buffer buf . The returned buffer 

contains a lineof format 

name:passwd:uid:gid:gecos:dir:shell 

T he passwd structure is defined in <pwd.h> as follows: 
struct passwd { 


char 

*pw_name; 

/‘username*/ 

char 

*pw_passwd; 

/* user password */ 

uid_t 

pw_uid; 

/* user id */ 

gid_t 

pw_gid; 

/* group id */ 

char 

*pw_gecos; 

/* real name */ 

char 

*pw_dir; 

/* home directory * 

char 

*pw_shell; 

/* shell program */ 


}; 

RETURN VALUE 

T he getpw( (function returns® on success, or -i if an error occurs. 

ERRORS 


ENOMEM 


Insufficient memory to allocate passwd structure 
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FILES 

/etc/passwd Password databasefile 

SEE ALSO 

fgetpwent(3), getpwent(3), setpwent(3), endpwent(3), getpwnam(3), getpwuid(3), putpwent(3), passwd(5) 

GNU, 27 May 1996 


getpwent, setpwent, endpwent 

getpwent, setpwent, endpwent— password file entry 

SYNOPSIS 

#include <pwd.h> 

#include <sys/types.h> 
struct passwd *getpwent(void); 
void setpwent(void); 
void endpwent(void); 

DESCRIPTION 

The getpwent o function returns a pointer to a structure containing the broken-out fields of a line from /etc/passwd. The 
first time it is called it returns the first entry; thereafter, it returns successive entries. 

The setpwent o function rewinds the file pointer to the beginning of the /etc/passwd file. 

The endpwent () function Closes the /etc/passwd file. 

The passwd structure is defined in <pwd.h> as follows: 


struct passwd { 
char 

*pw_name; 

/'username*/ 

char 

*pw_passwd; 

/* user password */ 

uid_t 

pw_uid; 

/* user id */ 

gid_t 

pw_gid; 

/* group id */ 

char 

*pw_gecos; 

/* real name */ 

char 

*pw_dir; 

/* home directory * 

char 

}; 

*pw_shell; 

/* shell program */ 

RETURN VALUE 




The getpwent ((function returns the passwd structure, or null if there are no more entries or an error occurs. 

ERRORS 

enomem Insufficient memory to allocate passwd structure. 

FILES 

/etc/passwd Password databasefile 

C0NF0RMST0 

SVID 3, BSD 4.3 

SEE ALSO 

fgetpwent(3), getpwnam(3), getpwuid(3), getpw(3), putpwent(3), passwd(5). 


GNU, 27 May 1996 
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getpwnam, getpwuid 

getpwnam, getpwuid —Get password file entry 

SYNOPSIS 

#include <pwd.h> 

#include <sys/types.h> 

struct passwd *getpwnam(const char * name); 

struct passwd *getpwuid(uid_t uid); 

DESCRIPTION 

The getpwnam o function returns a pointer to a structure containing the broken out fields of a line from /etc/passwd for the 
entry that matches the username name. 

The getpwuido function returns a pointer to a structure containing the broken-out fields of a line from /etc/passwd for the 
entry that matches the user UID uid. 

T he passwd structure is defined in <pwd.h> as follows: 


struct passwd { 
char 

*pw_name; 

/*username*/ 

char 

*pw_passwd; 

/* user password */ 

uid_t 

pw_uid; 

/* user id */ 

gid_t 

pw_gid; 

/* group id */ 

char 

*pw_gecos; 

/* real name */ 

char 

*pw_dir; 

/* home directory * 

char 

}; 

*pw_shell; 

/* shell program */ 

RETURN VALUE 




The getpwnam! >and getpwuido functions return the passwd structure or null if the matching entry is not found or an error 
occurs. 

ERRORS 

enomem Insufficient memory to allocate passwd structure. 

FILES 

/etc/passwd Password databasefile 

C0NF0RMST0 

SVID 3, PO SIX, BSD 4.3 

SEE ALSO 

fgetpwent(3), getpwent(3), setpwent(3), endpwent(3), getpw(3), putpwent(3), passwd(5) 

GNU, 21 May 1996 


fgetc,fgets,getc,getchar,gets,ungetc 

fgetc, fgets, getc, getchar, gets, ungetc— Input of characters and strings 

SYNOPSIS 


#include <stdio.h> 

int fgetc(FILE *s t r eam); 

char *fgets(char *s,int size, FILE *s t ream); 
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int getc(FILE *st r earn); 

int getchar(void); 

char *gets(char *s); 

int ungetc(int c, FILE *stream); 

DESCRIPTION 

fgetco reads the next character from stream and returns it as an unsigned char cast to an int, or eof on end of file or error, 
getc () is equivalent to fgetco except that it can be implemented as a macro that evaluates stream more than once 
getchar( ) is equivalent to getc (st d in). 

gets oreads a line from stdin into the buffer pointed to by s until either a terminating newline or EOF, which it replaces 
with \ 0 . N o check for buffer overrun is performed (seethefollowing "Bus" section). 

fgetso reads in at most one less than n characters from stream and stores them into the buffer pointed to by s. Reading stops 
after an eof or a newline. If a newline is read, it is stored into the buffer. \o isstored after the last character in the buffer. 

ungetco pushes c back to stream, cast to unsigned char, where it is available for subsequent read operations. Pushed-back 
characters will be returned in reverse order; only one pushback is guaranteed. 

Calls to the functions described here can be mixed with each other and with calls to other input functions from thestdio 
library for the same input stream. 

RETURN VALUES 

fgetco, getco, and getcharo return the character read as an unsigned char cast to an int, or eof on end of file or error, 
getso and fgetso return s on success, and null on error orwhen end offileoccurswhileno characters have been read, 
ungetco returnsc on success, or eof on error. 

C0NF0RMST0 

AN SI— C, POSIX.1 

BUGS 

Because it is impossible to tell without knowing the data in advance how many characters getso will read, and because 
getso will continue to store characters past the end of the buffer, it is extremely dangerous to use. It has been used to break 
computer security. U se fgetso instead. 

It is not advisable to mix cal Is to input functions from thestdio library with low-level calls to reado for the file descriptor 
associated with the input stream; the results will be undefined and very probably not what you want. 

SEE ALSO 

read(2), wnite(2), fopen(3), fread(3), scanf(3), puts(3), fseek(3), fernor(3) 

GNU, 4 April 1993 

getservent, getservbyname,getservbyport,setservent, 
endservent 

getservent, getservbyname, getservbyport, setservent, endservent —Get service entry 

SYNOPSIS 

#include <netdb.h> 

struct servent *getservent(void); 

struct servent *getservbyname(const char *name, const char *proto); 
struct servent *getservbyport(int port, const char *proto); 
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void setservent(int stayopen); 
void endservent(void); 

DESCRIPTION 

T he getservento function reads the next line from the file /etc/services and returns a structure, sen/ent, containing the 
broken out fields from the line The /etc/services fi le is opened if necessary. 

T he getservbynamei (function returns a ser vent structure for the line from /etc/services that matches the service name using 
protocol proto. 

T he getservbyport) (function returns a ser vent structure for the line that matches the port port given in network byte order 
using protocol proto. 

The setservent ( (function opens and rewinds the /etc/services file. If stayopen istrue(i), thefilewill not be closed between 
Calls to getservbynamei) and getservbyport (). 

T he endservent () function doses /etc/services. 

T he ser vent structure is defined in <netdb.h> asfollows: 
struct servent { 

char *s_name; /* official service name */ 
char **s_al i ases; /* alias list */ 
int sport ; /* port number */ 
char *s_prot o; /* protocol to use */ 

} 

T he mem bers of the s e r v e n t structu re are: 

s.name Theofficial name of the service. 

s.ai i ases A zero-terminated list of alternative names for the service. 

sport The port number for the service, given in network byte order. 

s.proto The name of the protocol to usewith thisservice 

RETURN VALUE 

The get servent () , getservbynamei ), and getservbyport () functions return the s er vent structure, or a null pointer if an error 
occurs or the end of thefile is reached. 

FILES 

/etc/services Services database file 

C0NF0RMST0 

BSD 4.3 



SEE ALSO 

getprotoent(3), getnetent(3), services(5) 


BSD, 22 April 1996 


getusershell, setusershell, endusershell 

getusershell, setusershell, endusershell— Get legal user shells 

SYNOPSIS 


#include <unistd.h> 
char *getusershell(void); 
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void setusershell(void); 
void endusershell(void); 


DESCRIPTION 

T he getusersheii( ) function returns the next line from the file /etc/shells, opening the file if necessary. The line should 
contain the path name of a valid user shell. If /etc/sheiis does not exist or is unreadable, getusersheiio behaves as if /bin/sh 
and /bin/csh were listed in the file. 

The setusershell( ) function rewinds / etc/shells. 

T he endusershell( ) function doses /etc/shells. 


RETURN VALUE 

The getusersheiio function returns a N U LL pointer on end of file 

FILES 

/etc/shells 

C0NF0RMST0 

BSD 4.3 

SEE ALSO 

shells(5) 


BSD, 4July 1993 


getutent, getutid, getutline,pututline,setutent,endutent, 
utmpname 

getutent, getutid, getutline, pututline, setutent, endutent, utmpname—Access utmp file entries 

SYNOPSIS 

//include <utmp.h> 

struct utmp *getutent(void); 

struct utmp *getutid(struct utmp *ut ); 

struct utmp *getutline(struct utmp *ut ); 

void pututline(struct utmp *ut); 

void setutent(void); 

void endutent(void); 

void utmpname(const char *f i I e); 

DESCRIPTION 

utmpname o sets the name of the utmp-format file for the other utmp functions to access. If utmpname o is not used to set the 
filename before the other functions are used, they assume path jjtmp, as defined in <paths.h>. 

setutent o rewinds the file pointer to the beginning of the utmp file. It is generally a good idea to call it before any of the 
other functions. 

endutent o closes the utmp file. It should be called when the user code is done accessing the file with the other functions. 

getutent o reads a line from the current file position in the utmp file. It returns a pointer to a structure containing the fields 
of theline. 

getutid ((searches forward from the current file position in theutmp file based on ut . If ut ->ut_type is run_lvl, bootjime, 
new_time, or oldtime, getutido will find the first entry whose ut_type field matches ut ->ut_type. If ut ->ut_type is 
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init_process, loginprocess, userprocess, or deadprocess, getutido will find the first entry whose ut_id field matches 

ut ->ut_id. 

getutiineo searches forward from the current file position in theutmp file. It scans entries whose ut type is user process or 
loginprocess and returns the first one whose ut_iine field matches ut ->ut_iine. 

pututiineo writes theutmp structure ut into the utmp file. It uses getutido to search for the proper place in the file to insert 
the new entry. If it cannot find an appropriate slot for ut , pututiineo will append the new entry to the end of the file. 

RETURN VALUE 

getutento, getutido, and getutiineo return a pointer to a struct utmp, which is defined in <utmp.h>. 

FILES 

/var/run/utmp — D atabase of currently logged-in users 
/var/iog/wtmp — D atabaseof past user logins 

C0NF0RMST0 

XPG 2, SVID 2, Linux FSSTN D 1.2 

SEE ALSO 

utmp(5) 

Linux libc5.0.0, 22 M arch 1995 

getw, putw 

getw, putw— Input and output of words (ints) 

SYNOPSIS 

#include <stdio.h> 

int getw(FILE *st r earn); 

int putw(int w,FILE*strearn); 

DESCRIPTION 

getw reads a word (that is an int) from st ream. It's provided for compatibility with SVID. I recommend you usetnead(3) 
instead, putw writes the word w (that is, an int) to stream. It is provided for compatibility with SVID, but I recommend you 
use twrite(3) instead. 

RETURN VALUES 

N ormally, getw returnstheword read, and putw returnstheword written. On error, they return eof. 

BUGS 

The value returned on error is also a legitimate data value. femor(3) can beused to distinguish between the two cases. 

C0NF0RMST0 

SVID 

SEE ALSO 

fread(3), fwrite(3), ferror(3), getc(3), putc(3) 



GNU, 16 September 1995 
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glob,globfree 

glob, globfree— Find pathnames matching a pattern; free memory from giobo 

SYNOPSIS 

#include <glob.h> 

int glob(const char *pattern, int flags, 
int errfunc (const char * epath, int eerrno), 
glob_t *pgl ob); 
void globfree(glob_t *pgIob); 

DESCRIPTION 

Thegiobo function searches for all the pathnames matching pat tern according to the rules used by the shell (see giob(7)). 

N o tilde expansion or parameter substitution isdone. 

The giobfreeo function frees the dynamically allocated storage from an earlier call to giob(). 

The results of a giobo call are stored in the structure pointed to bypgiob, which is a giob_t that is declared in <giob.h> as 

typedef struct 
{ 

int gl_patbc; /* Count of paths matched so far */ 

char **gl_pathv; /* List of matched pathnames. */ 
int gl_offs; /* Slots to reserve in 1 gl pathv 1 . */ 

int gl_flags; /* Flags for globbing */ 

} glob_t; 

Results are stored in dynamically allocated storage. 

T he parameter flags is made up of bitwise OR of zero or more the following symbolic constants, which modify the of 
behavior ofgiob(>: 

glob err Return on read error (because a directory does not have read permission, for example). 

glob mark Append a slash to each path which corresponds to a directory. 

glob nosort D on't sort the returned pathnames (they are by default). 

globdoofs pgi ob->gi _offs slotswill be reserved at the beginning of the list of strings in pgi ob->pathv. 

glob nocheck If no pattern matches, return the original pattern. 

glob append Append to the results of a previous call. D o not set this flag on the first invocation of giob(). 

glob noescape M eta characters cannot be quoted by backslashes. 

glob period A leading period can be matched by meta characters. 

If emfunc is not null, it will be called in case of an error with the arguments epath, a pointer to the path that failed, and 
eerrno, the value of errno as returned from one of the calls to opendiro, readdiro, or stat () . If errfunc returns nonzero, or 
if glob_err is set, giobo will terminate after the call to errfunc. 

Upon successful return, pgi ob ->gi _ pat he contains the number of matched pathnames and pgiob->gi_pathv a pointer to the 
list of matched pathnames. T hefirst pointer after the last pathname is null. 

It is possible to call giobo several times. In that case, theGLOBAPPEND flag has to be set in f i a g s on the second and later 
invocations. 

RETURN VALUES 

On successful completion, giobo returns 0 . Other possible returns are 
glob nospace For running out of memory, 

glob abend For a read error, and 

glob nomatch For no found matches. 
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EXAMPLES 

One example of use is the following code, which simulates typing in the shell: 

Is -1 *.c ../*.c 

glob_t globbuf; 
globbuf,gl_offs = 2; 

globe*.C", GLOBDOOFS, NULL, &globbuf); 

globC", GLOBDOOFS | GLOB_APPEND, NULL, &globbuf); 

globbuf.gl_pathv[0] = "Is"; 

globbuf. gl_pathv [ 1 ] = 11 -1"; 

execvp("Is", &globbuf.gl_pathv[0]); 

C0NF0RMST0 

Proposed POSIX.2 

BUGS 

The glob ((function may fail due to failure of underlying function calls, such asmaiioco or opendir(). These will store their 
error code in errno. 

POSIX.2 is not yet an approved standard; the information in this man page is subject to change. 

SEE ALSO 

ls( 1), sh(l), exec(2), stat(2), malloc(3), opendir(3), readdir(3), wordexp(3), glob(7) 

GNU, 13 May 1996 


hosts_access, hosts_ctl 

hosts_access, hosts_cti— Access-control library functions 

SYNOPSIS 

#include "log_tcp.h" 
extern int al I ow severity; 
extern int deny_severity ; 
int hosts_access(daemon, client) 
char *d a e mo n; 

struct client_info *client; 

int hosts_ctl(daemon, cl i ent name, cl i ent addr, cl i ent user ) 

char *d a e mo n; 

char *c I i e n t _ n a me; 

char *cl i ent addr ; 

char *cI i ent user ; 

DESCRIPTION 

The routines described in this document are part of the libwrap. a library. They implement a pattern-based access-control 
language with optional shell commands that are executed when a pattern fires. 

In all cases, the daemon argument should specify a daemon process name (ar gv[ o] value). The client host address should be a 
valid address, or fromjjnknown if the address lookup failed. The client hostname and username should be empty strings if no 
information is available, fromjjnknown if the lookup failed, or an actual hostname or username. 

hosts_access( ) consults the access-control tables described in thehosts_access(5) manual page. hosts_access() returns® if 
access should be denied. 

hosts_cti() is a wrapper around thehosts_access() routine with a perhaps more convenient interface (although it does not 
pass on enough information to support automated remote username lookups). hosts_cti() returns® if access should be 
denied. 
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Theal i ow_sever i ty and deny,sever i ty variables determine how accepted and rqected requests can be logged. They must be 
provided by the caller and can be modified by rulesin the access-control tables. 

DIAGNOSTICS 

Problems are reported viathesysiog daemon. 

SEE ALSO 

hosts_access(5) (format of the access control tables), hosts_options(5), optional extensions to the base language 

FILES 

/etc/hosts.access, /etc/hosts.deny access-control tables 

BUGS 

The functions described here do not make copies of their string-valued arguments. Beware of data from functions that 
overwrite their results on each call. 

hosts_access( ) uses the strtok() library function. This may i nterfere with other code that relies on strtoko. 

AUTHOR 

W ietse Venema (wietse@wzv.win.tue.nl) 

D epartment of M athematics and C omputing Science 
Eindhoven University of Technology 

Den Dolech 2, P.O. Box513, 5600 M B Eindhoven, TheN etherlands 

hcreate,hdestroy,hsearch 

hcreate, hdestroy, hsearch— H ash table management 

SYNOPSIS 

#include <search.h> 

ENTRY *hsearch(ENTRY item, ACTION action); 
int hcreate(unsigned nel ); 
void hdestroy(voi d); 

DESCRIPTION 

These three functionsallow theuserto createa hash tablethat associates a key with any data. 

First, thetablemust be created with thefunction hcreate(). nel isan estimate of the number of entries in thetable. 
hcreateo may adjust this value upward to improve the performance of the resulting hash table. TheGN U implementation 
of hsearchi ) will also enlarge thetable if it gets nearly full. maiioc(3) is used to allocate space for thetable. 

The corresponding function hdestroy! ) frees the memory occupied by the hash table so that a new table can be constructed, 
item is of type entry, which i s a typed ef defined in <search.h> and includes these elements: 

typedef struct entry 
{ 

char *key; 
char *da t a; 

} ENTRY; 

key points to the zero-terminated ASC11 string that is the search key. data points to the data associated with that key. (A 
pointer to a type other than character should be cast to pointer-to-character.) hsearch ((searches the hash table for an item 
with the same key as i tem, and if successful returns a pointer to it. act i on determines what hsearch o does after an unsuccess¬ 
ful search. A value of enter instructs it to insert the new item, whereas a value of find meansto return null. 
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RETURN VALUE 

hcreateo returns null if the hash table cannot be successfully installed. 

hsearcho returns null if act i on is enter and there is insufficient memory to expand the hash table, or if act i on is find and 
i tem cannot befound in the hash table. 

CONFORMSTO 

SVID, except that in SysV, the hash tablecannot grow. 

BUGS 

The implementation can manage only one hash table at a time. Individual hash table entries can be added, but not deleted. 

EXAMPLE 

The following program inserts 24 items into a hash table and then prints some of them: 

#include <stdio.h> 

#include <search.h> 

char *data[ ]={ "alpha", "bravo", "Charley", "delta", 

"echo", "foxtrot", "golf", "hotel", "india", "juliette", 

"kilo", "lima", "mike", "november", "oscar", "papa", 

"quebec", "romeo", "sierra", "tango", "uniform", 

"victor", "whiskey", "x-ray", "yankee", "zulu" 

}; 

int main() 

{ 

ENTRY e, *ep; 
int i ; 

/* start with small table, and let it grow */ 
hcreate(3); 

for (i = 0; i < 24; i ++) 

{ 

e, key = dat a[i ]; 

/* data is just an integer, instead of a pointer 
to something */ 
e. dat a = (char *)i ; 
ep = hsearch(e, ENTER) ; 

/* there should be no failures */ 

if(ep == NULL) {fprintf(stderr, "entry failed\n"); exit(1);} 

} 

for (i = 22; i < 26; i ++) 

/* print two entries from the table, and show that 
two are not in the table */ 

{ 

e, key = dat a[ i ] ; 
ep = hsearch(e, FIND) ; 

printf("%9.9s -> %9.9s:%d\n", e.key, ep?ep->key : "NULL", 
ep ?(int)(ep->d a t a ):0); 

} 

return 0; 

} 

SEE ALSO 

bsearch(3), lsearch(3), tsearch(3), malloc(3) 


GNU,30 September 1995 
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hypot 

hypot— Euclidean distance function 

SYNOPSIS 

#include <math.h> 

double hypot(double x, double y); 

DESCRIPTION 

The hypot o function returns the sqrt(x*x+y*y). This is the length of the hypotenuse of a right-angle triangle with sides of 
length x andy, or the distance of the point (x, y) from the origin. 

C0NF0RMST0 

SVID 3, BSD 4.3 

SEE ALSO 

sqrt(3) 

25Junel993 


index,rindex 

index, rindex— Locate character in string 

SYNOPSIS 

#include <string.h> 

char *index(const char *s,int c); 

char *rindex(const char *s ,int c); 

DESCRIPTION 

The index)) function returns a pointer to the first occurrence of the character c in the string s . 

The rindexo function returns a pointer to the last occurrence of the character c in the string s . 

The terminating null character is considered to be a part of the strings. 

RETURN VALUE 

The index)) and rindexo functions return a pointer to the matched character, or null if the character is not found. 

C0NF0RMST0 

BSD 4.3 

SEE ALSO 

memchr(3), strchr(3), strpbrk(3), strrchr(3), strsep(3), strspn(3), strstr(3), strtok(3) 

GNU, 12 April 1993 

inet_aton, inet_addr, inet_network, inet_ntoa, inet_makeaddr, 
inet_lnaof,inet_netof 

inet_aton, inet_addr, inet_network, inetjitoa, inet_makeaddr, inet_lnaof, inet_netof —Internet address-manipulation 
routines 
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SYNOPSIS 

#include <sys/socket.h> 

#include <netinet/in.h> 

#include <arpa/inet.h> 

int inet_aton(const char *cp, struct in_addr *inp); 
unsigned long int inet_addr(const char *cp); 
unsigned long int inet_network(const char *cp); 
char *inet_ntoa(struct in_addr in); 
struct in_addr inet_makeaddr(int net, int host); 
unsigned long int inet_lnaof(struct in_addr in); 
unsigned long int inet_netof(struct in_addr in); 


DESCRIPTION 

inet_aton() converts the I nternet host address c p from the standard numbers-and-dots notation into binary data and stores it 
in the structure that inp points to. inet_aton returns nonzero if the address is valid, and 0 if itisnot. 

T he inet_addn( (function converts the I nternet host address cp from numbers-and-dots notation into binary data in network 
byte order. If theinput isinvalid, -1 is returned. Thisisan obsolete interface to inet_aton; it is obsolete because -1 isavalid 
address (255.255.255.255), and inet_aton provides a cleaner way to indicate error return. 

T he inet_network( > function extracts the network number in network byte order from the address cp in numbers-and-dots 
notation. If theinput isinvalid, -1 is returned. 

T he inet_ntoa( ) function converts the I nternet host address given in network byte order to a string in standard numbers- 
and-dots notation. The string is returned in a statically allocated buffer, which subsequent calls will overwrite. 

Theinetjnakeaddro function makes an Internet host address in network byte order by combining the network number net 
with the local addresshost in network net , both in local host byte order. 

T he inet_inaof () function returns the local host address part of the I nternet address i n. The local host address is returned in 
local host byte order. 

T he inet_netof( (function returns the network number part of the I nternet address i n. The network number is returned in 
local host byte order. 

The Structure in_addr as used in inet_ntoa(), inet_makeaddr(), inet_lnoaf (), and inet_netof () is defined in netinet/in .h as 

struct in_addr { 
unsigned long int s_addr; 

} 

N otethat on the i80x86 the host byte order is Least Significant Byte first, whereas the network byte order, as used on the 
Internet, is M ost Significant Byte first. 

C0NF0RMST0 

BSD 4.3 


SEE ALSO 

gethostbyname(3), getnetent(3), hosts(5), networks(5) 


BSD, 3 September 1995 


infnan 

infnan— Dealswith infinite or not-a-number (N aN) result 

SYNOPSIS 


#include <math.h> 
double infnan(int error); 
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DESCRIPTION 

The infnan( ) function returns a suitable value for infinity and not-a-number (N aN) results. The value of error can be erange 
to represent infinity, or anything else to represent N aN. errno isalso set. 

RETURN VALUE 

If error is erange (Infinity), huge_val is returned. 

If error is -erange (-Infinity), -huge_val is returned. 

If error is anything else, NaN is returned. 

ERRORS 

erange Thevalueof error ispositiveor negative infinity. 

edom Thevalueof error is not-a-number (N aN). 

C0NF0RMST0 

BSD 4.3 

GNU, 2 Junel993 


initgroups 

initgroups — I nitializes the supplementary group access list 

SYNOPSIS 

#include <grp.h> 

#include <sys/types.h> 

int initgroups(const chan ‘user , gid_t group); 

DESCRIPTION 

The initgroupso function initializes the group access list by reading the group database /etc/group and using all groups of 
which user is a member. The additional group group isalso added to the list. 

RETURN VALUE 

The initgroups!) function returnso on success, or -i if an error occurs. 

ERRORS 

eperm The calling process does not have sufficient privileges. 

enomem Insufficient memory to allocate group information structure. 

FILES 

/etc/group group database file 

C0NF0RMST0 

SVID 3, BSD 4.3 

SEE ALSO 

getgroups(2), setgroups(2) 


GNU, 5 April 1993 
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inndcomm 

inndcomm— IN N D communication part of InterN etN ews library 

SYNOPSIS 

#include "inndcomm.h" 
int ICCopen() 
int ICCclose() 
void ICCsettimeout(i) 
int i ; 

int ICCcommand(c md, argv, replyp) 

char cmd; 

char *argv[]; 

char **r epl yp; 

int ICCcancel(mesgi d) 

char *me s g i d; 

int ICCreserve(why) 

char *why; 

int ICCpause(why) 

char *why ; 

int ICCgo(why) 

char *why ; 

extern char *1 CCf ai I ure; 

DESCRIPTION 

The routines described in this manual page are part of the InterN etN ews library, iibinn(3). They are used to send com¬ 
mands to a running innd(8) daemon on the local host. The letters ICC stand for Innd Control Command. 

iccopen creates a U N IX-domain datagram socket and binds it to the server's control socket. It returns-i on failure or 0 on 
success. This routine must be called before any other routine. 

iccdose closes any descriptors that have been created by iccopen. It returns -1 on failure or 0 on success. 

iccsettimeout can be called before any of the following routines to determine how long the library should wait before giving 
up on getting the server's reply. This is done by setting and catching a sigalrm signai(2). If the timeout islessthan 0, no 
reply will be waited for. Thesc_SHUTDowN, sc_xabort, and sc_xexec commands do not get a reply either. The default, which 
can be obtained by setting the timeout to 0, is to wait until the server replies. 

icccommand sends the command c md with parameters a r gv to the server. It returns -1 on error. If the server replies, and r e pi y p 
is not null, it will be filled in with an allocated buffer that contains the full text of the server's reply. This buffer is a string in 
the form <di gi t s ><s pa c e><t ext > where digits is the text value of the recommended exit code; 0 indicates success. Replies 
longer than 4,000 bytes will be truncated. The possible values of cmd are defined in the inndcomm. h header file. The param¬ 
eters for each command are described in ctimnd(8). This routine returns -1 on communication failure; on success it returns 
the exit status sent by the server, which will never be negative. 

icccancei sends a cancel m essage to the server, mesgi d isthe message ID of the article that should be canceled. The return 
value isthe same as for icccommand. 

iccpause, iccreserve, and iccgo send a pause, reserve, or go command to the server, respectively. If iccreserve is used, the 
why value used in theiccpause invocation must match; the value used in theiccgo invocation must always match the one 
used in theiccpause invocation. The return value for all three routines is the same as for icccommand. 

If any of these routines fail, theiccfaiiure vari able will identify the system call that failed. 

HISTORY 

W ritten by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

ctlinnd(8), innd(8), libinn(3). 



isalnum, isalpha, isascii, isbtank, iscntrl, isdigit, isgraph, islower, isprint, ispunct, ispace, isupper, isxdigit 
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insque,remque 

insque, remque— I nsert/ Remove an item from a queue 

SYNOPSIS 

#include <stdlib.h> 

void insque(struct qelem * elem, struct qelem * prev); 
void remque(struct qelem*elem); 

DESCRIPTION 

insque () and remqueo are functions for manipulating queues made from doubly linked lists. Each elementin this list is of 
type struct qelem. 

Theqeiem structure is defined as 

struct qelem { 
struct qelem *q_forw; 
struct qelem *q_back; 
char q_data[1]; 

}; 

insque o inserts the element pointed to by e i e m immediately after the element pointed to by prev, which must not be null. 
remqueo removes the element pointed to by e i emfrorn the doubly linked list. 

C0NF0RMST0 

SVR4 

BUGS 

T he q_data field is sometimes defined to be of type char *, and under Solaris 2.x, it doesn't appear to exist at all. 

The location of the prototypes for these functions differs among several versions of U NIX. Some systems pi ace them in 
<search.h>, others in <string.h>. Linux places them in <stdiib.h> because that seemsto makethemost sense. 

Some versionsof UNIX (such asHP-UX 10.x) do not define a struct qelem but rather have the arguments to insqueo and 
remqueO be Of type void *. 

GNU, 30 October 1996 

isalnum, isalpha, isascii, isblank, iscntrl, isdigit, isgraph, 
islower, isprint, ispunct, isspace, isupper,isxdigit 

isalnum, isalpha, isascii, isblank, iscntrl, isdigit, isgraph, islower, isprint, ispunct, isspace, isupper, isxdigit— 
Character classification routines 

SYNOPSIS 

#include <ctype.h> 
int isalnum (int c); 
int isalpha (int c); 
int isascii (int c); 
int isblank (int c); 
int iscntrl (int c); 
int isdigit (int c); 
int isgraph (int c); 
int islower (int c); 
int isprint (int c); 
int ispunct (int c); 
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int isspace (int c); 
int isupper (int c); 
int isxdigit (int c); 


DESCRIPTION 


These functions check whether c, which must have the value of an unsigned char or eof, falls into a certain character class 
according to the current locale: 


isalnum() 
isalpha() 


isascii() 

isblank() 
iscntrl() 
isdigitO 
isgraph() 
islower() 
isprint() 
ispunct() 
isspace() 

isupper() 
isxdigit() 


Checksforan alphanumeric character; it is equivalent to (isaipha(c) ] | isdigit(c) ). 
Checksforan alphabetic character; in the standard C locale, it is equivalent to (isupper(c) ] | 
isiower(c) ). In some locales, there may be additional characters for which isaiphao is true— 
letters that are neither uppercase nor lowercase. 

C hecks whether c is a 7-bit unsigned char value that fits into the ASCII character set. This 
function isa BSD extension and isalso an SVID extension. 

Checks for a blank character; that is, a space or a tab. This function isaGNU extension. 

C hecksfor a control character. 

C hecksfor a digit (0 through 9). 

C hecksfor any printable character except space. 

C hecksfor a lowercase character. 

C hecksfor any printable character, includi ng space. 

Checks for any printable character that is not a space or an alphanumeric character. 

C hecksfor whitespace characters. They are space, form-feed ( 1 \f ■), newline ( 1 \n 1 ), carriage 
return ('\r'), horizontal tab ( 1 \t 1 ), and vertical tab ( 1 \v 1 ). 

C hecksfor an uppercase letter. 

C hecksfor a hexadecimal digit (that isoneof01234567890abcdefABC D E F). 


RETURN VALUE 

The values returned are nonzero if the character c falls into the tested class, and 0 if it does not. 


C0NF0RMST0 

AN SI C, BSD 4.3. isasciio isa BSD extension and isalso an SVID extension, isblank 0 isaGNU extension. 

BUGS 

The details of what characters belong in which class depend on the current locale. For example, isupper) ) will not recognize 
an A with an umlaut (A) as an uppercase letter in thedefault C locale. 

SEE ALSO 

tolower(3), toupper(3), setlocale(3), ascii(7), locale(7) 

GNU, 2 September 1995 


isatty 

isatty— Tests whether this descriptor refers to aterminal 

SYNOPSIS 

#include <unistd.h> 
int isatty (int desc ); 

DESCRIPTION 

isatty returns 1 if desc is an open descriptor connected to aterminal, and 0 otherwise. 
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CONFORMSTO 

SVID, AT&T, X/O PEN , BSD 4.3 

SEE ALSO 

fstat(2), ttyname(3) 

Linux, 20 April 1995 


isinf,isnan,finite 

isint, isnan, finite— Test for infinity or not-a-number (N aN ) 

SYNOPSIS 

#include <math.h> 
int isinf (double value); 
int isnan(double value); 
int finite(double value); 

DESCRIPTION 

T he isinf o function returns -i if value represents negative infinity, i if value represents positive infinity, and 0 otherwise. 

T he isnan 0 function returns a nonzero value if vai ue is not-a-number (N aN), and 0 otherwise. 

The finite!) function returns a nonzero value ifvai ue isfiniteor is not a not-a-number (N aN) value, and 0 otherwise. 

conforms™ 

BSD 4.3 

GNU, 2Junel993 


j0.j1i jn,y0,y1,yn 

jo, j 1 , jn, y@, yi, yn— Bessel functions 

SYNOPSIS 

#include <math.h> 
double j0(double x); 
double jl (double x); 
double jn(int n, double x); 
double y0(double x); 
double yl (double x); 
double yn(int n, double x); 

DESCRIPTION 

The j 0 () and jio functions return Bessel functionsofx of the first kind of orders 0 and 1, respectively. The jn( (function 
returns the Bessel function of x of the first kind of order n. 

T he yo() and yi() functions return Bessel functionsofx of thesecond kind, ordersO and 1, respectively. The yn( (function 
returns the Bessel function ofx of thesecond kind, ordern. 

Forthefunctionsyoo, yi 0 and yn o.the value of x must be positive. For negativevaluesofx, these functions return 

-HUGE_VAL. 

conforms™ 

SVID 3, BSD 4.3 
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BUGS 

T here are errors of up to 2e-16 in the values returned by joo, ji (), and jno forvaluesofx between -8 and 8. 

26 Junel993 


killpg 

kiiipg — Sends a signal to all members of a process group 

SYNOPSIS 

#include <signal.h> 

int killpg(pid_t pidgrp, int signal ); 

DESCRIPTION 

The kiiipg o function causes the signal signal to be sent to all the processes in the process group pi dgr p or to the processes' 
own process group if pidgrp is equal to 0. 

It is equivalent to kill( - pidgrp, signal);. 

RETURN VALUE 

The value returned is -i on error, or 0 for success. 

ERRORS 

Errors are returned in errno and can be one of the following: 

einval Signal is invalid. 

esrch Process group does not exist. 

eperm TheuserlD of the calling process is not equal to that of the process the signal is sent to, and the user ID is 

not that of the super-user. 

SEE ALSO 

kill(2), signal(2), signal(7) 

GNU, 4 April 1993 


labs 

labs— C omputes the absolute value of a long integer 

SYNOPSIS 

#include <stdlib.h> 
long int labs(long int j ); 

DESCRIPTION 

T he labs 0 function computes the absolute value of the long integer argument). 

RETURN VALUE 

Returns the absolute value of the long integer argument. 

C0NF0RMST0 

SVID 3, BSD 4.3, ISO 9899 
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NOTES 

T rying to take the absolute value of the most negative integer is not defined. 

SEE ALSO 

abs(3), ceil(3), floor(3), fabs(3), rint(3) 

GNU, 6Junel993 


ldexp 

ldexp— M ultiplies floating-point number by integral power of 2 

SYNOPSIS 

#include <math.h> 

double ldexp(double x, int exp); 

DESCRIPTION 

T he ldexp o function returns the result of multiplying the floating-point number % by 2 raised to the power exp. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

frexp(3), modf(3) 

BSD, 6Junel993 


ldiv 

idiv— Computes the quotient and remainder of long integer division 

SYNOPSIS 

#include <stdlib.h> 

ldiv_t ldiv(long int numer , long int denom); 

DESCRIPTION 

Theidivo function computes the value numer/denom and returns the quotient and remainder in a structure named idiv_t 
that contains two long integer members named quot and rem. 

RETURN VALUE 

Theidiv_t structure 

C0NF0RMST0 

SVID 3, BSD 4.3, ISO 9899 

SEE ALSO 

div(3) 

GNU, 29 March 1993 
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lgamma 

igamma— L ogs gam ma functi on 

SYNOPSIS 

#include <math.h> 
double lgamma(double x); 

DESCRIPTION 

T he igamma() function returns the log of the absolute value of the G amma function. T he sign of the G amma function is 
returned in theexternal integer si gngam. 

For negative integer values of*, igamma o returns huge_val, and errno is set to erange. 

ERRORS 

erange Invalid argument—negative integer value of*. 

C0NF0RMST0 

SVID 3, BSD 4.3 

SEE ALSO 

infnan(3) 

BSD, 25Junel993 


libinn 

libinn— InterN etN ews library routines 

SYNOPSIS 

#include "libinn.h" 
typedef struct _TIMEINF0 { 
time_t t i me; 
long usee; 
long t zone; 

} TIMEINFO; 

char *GenerateMessageID() 

void HeaderCleanFrom(from) 
char *f r om; 

char *HeaderFind(Art i c I e, Header, size) 
char *Art i cl e; 
char *Hea der ; 
int size; 

FILE *CAopen(FromServer, ToServer) 

FILE *FromServer ; 

FILE *ToServer ; 

FILE *CAlistopen(Fr omSer ver, ToServer, request) 
FILE *FromServer ; 

FILE *ToServer ; 
char *request ; 
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void CAclose() 

struct _DDHANDLE *DDstart(FromServer, ToServer) 

FILE *FromServer ; 

FILE *ToServer ; 

} DDHANDLE; 

void DDcheck(h, group) 

DDHANDLE *h; 
char *gr oup; 

char * DDend(h) 

DDHANDLE *h; 

void CloseOnExec(fd, flag) 
int f d; 
int flag; 

int SetNonBlocking(f d, flag) 
int f d; 
int flag; 

int LockFile(f d, flag) 
int f d; 
int flag; 

char * GetConfigValue(val ue) 
char *vaI ue; 

char * GetFileConfigValue(val ue) 
char *vaI ue; 

char * GetFQDN() 

char * GetModeratorAddress(group) 
char *gr oup; 

int GetResourceUsage(userti me, systime) 
double *usert i me; 
double *syst i me; 

int GetTimelnfofnow) 

TIMEINFO *now; 

int NNTPlocalopen(Fr omSer ver p, ToServerp, errbuff) 

FILE **F r omSer ver p; 

FILE **ToSer ver p; 
char *er r buf f ; 

int NNTPremoteopen(Fr omSer ver p, ToServerp, errbuff) 
FILE **F r omSer ver p; 

FILE **ToSer ver p; 
char *er r buf f ; 

int NNTPconnect(host, FromServerp, ToServerp, errbuff) 
char *host ; 

FILE **F r omSer ver p; 

FILE **ToSer ver p; 
char *er r buf f ; 


int NNTPcheckarticleftext ) 
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char *text ; 

int NNTPsendarticle(t ext, ToServer, Terminate) 
char *text ; 

FILE *ToServer ; 
int Ter mi nat e; 

int NNTPsendpassword(server, FromServer, ToServer) 
char *server ; 

FILE *FromServer ; 

FILE *ToServer ; 

void Radix32(val ue, p) 
unsigned long val ue; 
char *p; 

char * ReadInFile(name, Sbp) 
char *n a me; 
struct stat *Sbp; 

char * ReadInDescriptor(fd, Sbp) 
int f d; 

struct stat *Sbp; 


char * INNVersion() 

DESCRIPTION 

libinn is a library of utility routines for manipulating U senet articles and related data. It is not necessary to use the header file 
libinn.h; if it is not available, it is only necessary to properly declare the timeinfo datatype, as shown in the preceding code. 

GenerateMessageiD uses the current time process ID, and fully qualified domain name of the local host to create a M essage 
ID header that is highly likely to be unique. The returned value points to static space that is reused on subsequent calls. 

HeadercieanFrom removes the extraneous information from the value of a From or Repiy-To header and leaves j ust the official 
mailing address. In particular, the following transformations are made to thefrom parameter: 

address -> address 
address (stuff ) -> address 
stuff <a d d r e s s >-> address 

Thetransformationsaresimpleand are based on RFC 1036, which limits theformat of the header. 

HeaderFind searches through Article looking for the specified Header .size should be the length of the header name It 
returns a pointer to the value of the header, skipping leading whitespace, or null if the header cannot be found. Article 
should be a standard C string containing the text of the article the end of a header is indicated by a blank line: two 
consecutive \n characters. 

cAopen and cAciose provide news clients with access to the active file; thecA stands for Client Active. cAopen opens the 
active(5) file for reading. It returns a pointer to an open file, or null on error. If a local or an N FS-mounted copy exists, 
CAopen will use that file. TheFromServer and ToServer parameters should be files connected to the N N TP server for input 
and output, respectively. (See the discussions of NNTPremoteopen and NNTPiocaiopen later in this section.) If either parameter is 
null, CAopen will just return null if the file is not locally available. If neither is null, CAopen will use them to query the N NTP 
server using the "list" command to make a local temporary copy. 

T he cAiistopen sends a "list" command to the server and returns a temporary file containing the results T he r eques t 
parameter, if not null, will be sent as an argument to the command. Unlike CAopen, this routine will never use a locally 
available copy of the active file. 

CAciose closes the active file and removes any temporary file that might have been created by CAopen orcAiistopen. 
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cioseonExec can make a descri ptor close-on-exec so that it is not shared with any child processes. If the flag is nonzero, the file 
is so marked; if it is a, the close-on-exec mode is cleared. 

DDstart, DDcheck, and DDend are used to set the Distribution header; theDD stands for D efault D istribution. The 
distrib.pats(5) file isconsulted to determine the proper value for the Distribution header after all newsgroups have been 
checked. DDstart begins the parsing. It returns a pointer to an opaque handle that should be used on subsequent calls. The 
FromServer and ToServer parameters should be files connected to the N NT P server for input and output, respectively. If 
either parameter isNuu, an empty default will ultimately be returned if thefile is not locally available. 

DDcheck should be called with the handle, h, returned by DDstart and a new group, group, to check. It can be called as often as 
necessary. 

DDend releases any state maintained in the handle and returns an allocated copy of the text that should be used for the 
Distribution header. 

setNonBiocking enables (if flag isnonzero) or disables (iff i ag iso) non-blocking I/O on the indicated descriptor. It returns 
-i on failure and o on success. 

LockFiie tries to lock thefi le descriptor f d . If f i ag isnonzero it will block until the lock can be made; otherwise it will return 
-i if the file cannot be locked. It returns-i on failure and 0 on success. 

Getcont igvaiue returns the value of the specified configuration parameter. (Seeinn.cont(5) for details on the parameters and 
their interpretation.) The returned value points to static space that isreused on subsequent calls. 

GetFiiecontigvaiue returns the specified configuration parameter from the inn. cont file without checking for any defaults. 
The returned value points to static space that isreused on subsequent calls or null if the value is not present. 

GetFQDN returns the fully qualified domain name of the local host. The returned value points to static space that isreused on 
subsequent calls, or null on error. 

GetModeratorAddress returns the mailing address of the moderator for the specified group or null on error. (Seemoderators(5) 
for details on how the address is determined.) GetModeratorAddress does no checking to see if the specified group is actually 
moderated. The returned value points to static space that isreused on subsequent calls. 

GetResourceusage fills in the us er t i me and systi me parameters with the total user and system time used by the current process 
and any children it may have spawned. It gets the values by doingatimes(2) system call. It returns -1 on failure, or 0 on 
success. 

GetTimeinto fills in the now parameter with information about the current time and t zone. The t i me and usee fields will be 
filled in by a call to gettimeofday(2).Theti me field will be filled in by a call to time(2), and the usee field will beset to @.The 
t zone field will be filled in with the current offset from GMT. This is done by calling iocaitime(3) and taking the value of 
thet m_gmt off field, negating it, and dividing it by 60. This is done by calling iocaitime(3) and comparing the value with that 
returned by a call to gmtime(3). For efficiency, thet zone field isonly recalculated if more than an hour has passed since the 
last time GetTimeinto was called. T his routine returns-i on failure, and 0 on success. 

NNTPiocaiopen opens a connection to the private port of an InterN etN ews server running on the local host. It returns -1 on 
failure, or 0 on success. FromServerp andToServer p will be filled in with files that can be used to communicate with the 
server, err buff can either be null or a pointer to a buffer at least 512 bytes long. If it is not null, and the server refuses the 
connection, it will be filled in with the text of the server's reply. This routine is not for general use; it is a subroutine for 
compatibility with systems that have U N IX-domain stream sockets. It always returns- 1 . 

NNTPremoteopen does the same as NNTPiocaiopen, except that it callsGetconfigvaiue to find the name of the local server and 
opens a connection to thestandard N NTP port. Any client program can use this routine. It returns -1 on failure, oro on 
success. 

NNTPconnect is the same as NNTPremoteopen, except that the desired host is given as the host parameter. 

NNTPcheckarticie verifies that the text meets the N NTP limitations on line length. It returns -1 on failure, or 0 if the text is 
valid. 
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NNTPsendarticie writes text on ToSer ver using N NTP conventions for line termination. T hetext should consist of one or 
more lines ending with a newline. I f t e r mi nate isnonzero, theroutinewill also write theN NTP data-termination marker on 
thestream. It returns-i on failure, or 0 on success. 

NNTPsendpassword sends authentication information to an N NTP server by finding the appropriate entry in the 
passwd. nntp(5) file server Contains the name Of the host; GetConfigValue will be used if server is NULL. FromServer and 
ToSer ver should be files that are connected to the server. N 0 action is taken if the specified host is not listed in the password 
file. 

Radix32 converts the number in vai ue into a radix-32 string in the buffer pointed to by p. The number is split into five-bit 
pieces, and each piece is converted into a character using the alphabet 0... 9a... v to represent the numbers 0-32. Only the 
lowest 32 bitsof vai ue are used, so p need only point to a buffer of eight bytes (seven characters and the trailing \«). 

ReadinFiie reads the file named name into allocated memory, appending a terminating \® byte. It returns a pointer to the 
space, or null on error. If sbp is not null, it is taken as the address of a place to store the results of a stat(2) call. 

ReadinDescriptor performs the same function asReadinFiie, except that td refers to an al ready-open file. 
iNNVersion returns a pointer to a string identifying the IN N version, suitable for printing in logon banners. 

EXAMPLES 

char *p; 
char *Arti cl e; 
char buff[ 2 5 6 ] ; 

FILE *F; 

FILE *ToServer ; 

FILE *FromServer ; 

if ((p = HeaderFind(Art i c I e, "From", 4)) == NULL) 

Fatal("Can't find From line"); 

(void)strcpy(buff, p); 

HeaderCleanFrom(buff ); 

if ((F = CAopen(FromServer, ToServer )) == NULL) 

Fatal("Can't open active file"); 

/* Don't pass the file on to our children. */ 

CloseOnExec(fileno(F), 1); 

/* Make a local copy. */ 

p = ReadInDescriptor(fileno(F), (struct stat *)NULL); 

/* Close the file. */ 

CAclose(); 

if (NNTPremoteopen(&FromServer , &ToServer) < 0) 

Fatal("Can't connect to server"); 
if ((p = GetModeratorAddress("comp.sources.unix")) == NULL) 

Fatal("Can't find moderator's address"); 

HISTORY 

W ritten by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

active(5), dbz(3z), parsedate(3), inn.conf(5), inndcomm(3), moderators(5), passwd.nntp(5) 

GNU, 30 October 1996 
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SYNOPSIS 

#include <pbm.h> 
cc ... libpbm.a 

DESCRIPTION-PACKAGEWIDE ROUTINES 

The following sections describe string and file management routines available in libpbm. 

KEYWORD MATCHING 

T he following does a case-in sensitive match of st r against key wo r d: 
int pm_keymatch( char* str, char* keyword, int minchars ) 

str can bea leading substring of keyword, but at least mi nchars must be present. 

LOG BASE TWO 

Thisconverts between amaxvai and theminimum number of bits required to hold it: 

int pm_maxvaltobits(int maxval ) 
int pm_bitstomaxval(int bits) 

MESSAGES AND ERRORS 

This is a printf o-style routine to write an informational message 
void pm_message(char* f mt , ... ) 

T his is a printf o style routine to write an error message and abort: 
void pm_error(char* f mt , ... ) 

The foil owing writes a usage message; thestring should indicate what arguments are to be provided to the program: 
void pm_usage(char* usage) 

GENERIC FILE MANAGEMENT 

T he following opens thegiven filefor reading, with appropriate error checking: 

FILE* pm_openr(char* name) 

A filenameof - is taken as equivalent to stdin. 

The foil owing opens the given filefor writing, with appropriate error checking: 

FILE* pm_openw(char* name) 

The foil owing closes the file descriptor, with appropriate error checking: 

void pm_close(FILE* fp) 

ENDIAN I/O 

Thefollowing are routines to read and write short and long intsin either big- or little-endian byte order: 

int pm_readbigshort(FILE* in, short* sP) 
int pm_writebigshort(FILE* out , short s) 
int pm_readbiglong(FILE* in, long* IP) 
int pm_writebiglong(FILE* out , long I ) 
int pm_readlittleshort(FILE* in, short* sP) 
int pm_writelittleshort(FILE* out , short s) 
int pm_readlittlelong(FILE* in, long* IP) 
int pm_writelittlelong(FILE* out , long I ) 

DESCRIPTION-PBM-SPECIFIC ROUTINES 

Thefollowing sections describe file management routines available in libpbm. 
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TYPES AND CONSTANTS 

Each bit should contain only the values of pbm_white or pbm_black: 

typedef ... bit; 

#define PBM_WHITE ... 

#define PBM_BLACK ... 

T hese are routines for distinguishing different fi le formats and types: 

#define PBM_FORMAT ... 

#define RPBM_FORMAT ... 

#define PBM_TYPE PBM_FORMAT 
#define PBM_FORMAT TYPE(f ) ... 

INITIALIZATION 

All PBM programs must call this routine: 
void pbm_init(int* argcP, char* argv[] ) 

MEMORY MANAGEMENT 

T his allocates an array of bits: 

bit** pbm_allocarray(int cols, int rows) 

T his allocates a row of the given number of bits: 
bit* pbm_allocrow(int cols) 

This frees the array allocated with pbm_aiiocarray() containing the given number of rows: 
void pbm_freearray(bit** bits, int rows) 

This frees a row of bits: 
void pbm_freerow(bit* bitrow) 

READING FILES 

This reads the header from a PBM file filling in the r o m, col s, and format variables: 
void pbm_readpbminit(FILE* fp, int* coIsP, int* rowsP, int* formatP) 

This reads a row of bits into the b i trow array (format and cols are filled in by pbm_readpbminito): 
void pbm_readpbmrow(FILE* fp, bit* bitrow, int cols, int format) 

This function combines pbm_readpbminit(), pbm_allocarray( ), and pbm_readpbmrow() : 
bit** pbm_readpbm(FILE* fp, int* coIsP, int* rowsP) 

It reads an entire bitmap file into memory, returning the allocated array and filling in the rows and cols variables. 

This reads an entire file or input stream of unknown size to a buffer and allocates more memory as needed: 
char* pm_read unknown size(FILE* fp, long* nread) 

T he calling routine has to free the allocated buffer with treed ■ pm_read_unknown_size( ) returns a pointer to the allocated 
buffer; the nread argument returns the number of bytes read. 

WRITING FILES 

T his writes the header for a portable bitmap file: 

void pbm_writepbminit(FILE* fp, int cols, int rows, int forceplain) 

Theforcepi ai n flag forces a plai n-format fi le to be written, as opposed to a raw-format one 
T his writes a row from a portable bitmap: 

void pbm_writepbmrow(FILE* fp, bit* bitrow, int cols, int forceplain) 
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This writes the header and all data for a portable bitmap: 

void pbm_writepbm(FILE* fp, bit** bits, int cols, int rows, int forceplain) 

Thisfunction combines pbm_writepbminit() and pbm_writepbmrow(). 

SEE ALSO 

libpgm(3), libppm(3), libpnm(3) 

AUTHOR 

Copyright® 1989,1991 by Tony H ansen and J ef Poskanzer 

libpgm 

libpgm— Functions to support portable graymap programs 

SYNOPSIS 

#include <pgm.h> 

cc ... libpgm.a libpbm.a 

DESCRIPTION 

T he following sections describe memory and file management routines available in libpgm. 

TYPES AND CONSTANTS 

Each gray should contain only the values between 0 and pgm_maxmaxval. 

pgmjjbmmaxvai isthe ma x v a i used when a PGM program reads a PBM file N ormally it is i, but for some programs, a larger 
value gives better results 

typedef ... gray; 

#define PGMJIAXMAXVAL . .. 
extern gray pgm_pbmmaxval; 

The foil owing are for distinguishing different file formats and types: 

#define PGM_FORMAT ... 

#define RPGM_FORMAT ... 

#define PGM_TVPE PGM FORMAT 
int PGM_FORMAT_TYPEf int format) 

INITIALIZATION 

All PGM programs must call thisroutine: 
void pgm_init(int* argcP, char* a r g v[] ) 

MEMORY MANAGEMENT 

T his allocates an array of grays: 

gray** pgm_allocarray(int cols, int rows) 

T his allocates a row of thegiven number of grays: 
gray* pgm_allocrow(int cols) 

This frees the array allocated with pgm_aiiocarray() containing the given number of rows: 
void pgm_freearray(gray** grays, int rows) 

This frees a row of grays: 
void pgm_freerow(gray* gray row) 
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READING FILES 

This reads the header from a PGM file, filling in ther o»s, col s, ma x v a i , and for mat variables: 

void pgm_readpgminit(FILE* fp, int* coIsP, int* rowsP, gray* maxvalP, 
int* f or mat P) 

This reads a row of grays into thegrayrow array, format, cols, and maxvai are filled in by pgm_readpgminit(): 
void pgm_readpgmrow(FILE* fp, gray* grayrow, int cols, gray maxvai, int format) 

This function combines pgm_readpgminit(), pgm_allocarray( ), and pgm_readpgmrow() : 
gray** pgm_readpgm(FILE* fp, int* coIsP, int* rowsP, gray* maxvalP) 

It reads an entire graymap file into memory, returning the allocated array and filling in the rows, col s, and max# a i variables. 

WRITING FILES 

T hiswritesthe header for a portable graymap file 

void pgm_writepgminit( FILE* fp, int cols, int rows, gray maxvai , 
int forceplain ) 

Theforcepi ai n flag forces a plain-format file to be written, as opposed to a raw-format one. 

T his writes a row from a portable graymap: 

void pgm_writepgmrow(FILE* fp, gray* grayrow, int cols, gray maxvai , 
int forceplain) 

This function combi nespgm_writepgminit() and pgm_writepgmrow( >; it writes the header and all data for a portable graymap: 
void pgm_writepgm( FILE* fp, gray** grays, int col s, int rows , gray maxvai , int forcepl ai n) 

SEE ALSO 

libpbm(3), libppm(3), libpnm(3) 

AUTHOR 

Copyright ® 1989,1991 by Tony H ansen and Jef Poskanzer. 

libpnm 

libpnm— Functionsto support portable anymap programs 

SYNOPSIS 

#include <pnm.h> 

cc ... libpnm.a libppm.a libpgm.a libpbm.a 

DESCRIPTION 

T he following sections describe memory and file management routines available in libpnm. 

TYPES AND CONSTANTS 

Each xei contains three xeivais, each of which should contain only a value between 0 and pnm_maxmaxval. pnm_pbmmaxvai is 
the maxvai used when a PN M program reads a PBM file. N ormally it is 1 , but for some programs, a larger value gives better 
results. 

typedef ... xel; 
typedef ... xelval; 

#define PNMJIAXMAXVAL . .. 
extern xelval pnm_pbmmaxval; 
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XEL MANIPULATIONS 

This macro extracts a single value from an xei when you know it's from a PBM or PGM file: 

xelval PNM_GET1( xel x ) 

W hen the xei is from a PPM file use ppm getro, ppm_getg<), and ppm getb<). 

This macro assigns a single value to an xei when you know it's from a PBM or PGM file: 

void PNM_ASSIGN1( xel x, xelval v ) 

When the xei isfrom a PPM file useppM_AssiGN(). 

This macro checks two xeisfor equality: 

int PNM_EQUAL( xel x, xel y ) 

Thisoneisfordistinguishing different fi le types: 

int PNM_FORMAT TYPE) int format ) 

INITIALIZATION 

All PNM programs must call thisroutine: 

void pnm_init( int* argcP, char* argv[] ) 

MEMORY MANAGEMENT 

This allocates an array of xeis: 

xel** pnm_allocarray( int cols, int rows ) 

T his allocates a row of thegiven number of xeis: 
xel* pnm_allocrow( int cols ) 

This frees the array allocated with pnm_aiiocarray() that contains the given number of rows: 
void pnm_freearray( xel** xeis, int rows ) 

Thisfreesa row of xeis: 

void pnm_freerow( xel* xelrow ) 

READING FILES 

This reads the header from a PN M file, filling in the rows, cols, maxvai, and format variables: 

void pnm_readpnminit( FILE* fp, int* colsP, int* rowsP, xelval* maxvalP, 
int* formatP ) 

This reads a row of xeis into thexeirow array, format, cols, and maxvai arefilled in by pnm_readpnminit(): 
void pnm_readpnmrow( FILE* fp, xel* xelrow, int cols, xelval maxvai, int format ) 

This reads an entire anymap file into memory, returning the allocated array and filling in the rows, cols, maxvai, and format 
variables: 

xel** pnm_readpnm( FILE* fp, int* colsP, int* rowsP, xelval* maxvalP, 
int* formatP ) 

Thisfunction combines pnm_readpnminito, pnm_aiiocarray( ), and pnm_readpnmrow(). U n like the equivalent functions in 
PBM, PGM, and PPM, it returns the format so you can tell what type the file is. 

WRITING FILES 

T his writes the header for a portableanymap file: 

void pnm_writepnminit( FILE* fp, int cols, int rows, xelval maxvai, int format, 
int force-plain) 
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Unlike the equivalent functions in PBM, PGM, and PPM, you have to specify the output type. The forcepiain flag forces a 
plain-format fileto be written, as opposed to a raw-form at one. 

This writes a row from a portable anymap: 

void pnm_writepnmrow( FILE* fp, xel* xelrow, int cols, xelval maxval, int format, 
int forcepiain ) 

T his writes the header and all data for a portable anymap: 

void pnm_writepnm( FILE* fp, xel** xels, int cols, int rows, xelval maxval, int format, 
int forcepiain ) 

This function combi nespnm_writepnminit() and pnm_writepnmrow(). 

FORMAT PROMOTION 

This promotes a row of xels from one maxval and format to a new set: 

void pnm_promoteformatrow( xel* xelrow, int cols, xelval maxval, int format, xelval new-maxval, 
int newformat ) 

U se this when combining multiple anymaps of different types— just take the maxi mum value of themaxvais and the max of 
the formats and promote them all to that. 

T his promotes an entire anymap: 

void pnm_promoteformat( xel** xels, int cols, int rows, xelval maxval, 
int format, xelval newmaxval, int newformat ) 

XEL MANIPULATION 

These return a white or black xei, respectively, for the given maxval and format: 

xel pnm_whitexel( xelval maxval, int format ) 
xel pnm_blackxel( xelval maxval, int format ) 

This inverts an xei: 

void pnm_invertxel( xel* x, xelval maxval, int format ) 

Thisfiguresout an appropriate background xei based on this row: 

xel pnm_backgroundxelrow( xel* xelrow, int cols, xelval maxval, int format ) 

Thisfiguresout a background xei based on an entire anymap: 

xel pnm_backgroundxel( xel** xels, int cols, int rows, xelval maxval, 
int format ) 

Thiscan do a slightly better job than pnm_backgroundxeirow(). 

SEE ALSO 

pbm(3), pgm(3), ppm(3) 

AUTHOR 

Copyright® 1989,1991 by Tony H ansen and Jef Poskanzer. 
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libppm 

libppm— Functions to support portable pi xmap programs 

SYNOPSIS 

#include <ppm.h> 

cc ... libppm.a libpgm.a libpbm.a 

TYPES AND CONSTANTS 

typedef ... pixel; 
typedef ... pixval; 

#define PPMJIAXMAXVAL . . . 
extern pixval ppm_pbmmaxval; 

Each pixel contains three pixvais, each of which should contain only the values between 0 and ppm_maxmaxval. ppm_pbmmaxvai 
is the maxvai used when a ppm program readsaPBM file N ormally it isl; however, for some programs a larger value gives 
better results 

For distinguishing different file formats and types, use 

#define PPM_FORMAT ... 

#define RPPM_FORMAT ... 

#define PPM_TVPE PPMFORMAT 
int PPM_FORMAT_TYPEf int format ) 

These three macros retrieve thered, green, or bluevaluefrom thegiven pixel: 

pixval PPM_GETR( pixel p ) 
pixval PPM_GETG( pixel p ) 
pixval PPM_GETB( pixel p ) 

This macro assigns the given red, green, and blue values to the pixel: 

void PPM_ASSIGN( pixel p, pixval red, pixval grn, pixval blu ) 

This macro checks two pixels for equality: 

int PPM_EQUAL( pixel p, pixel q ) 

The following macro scales the colors of pixel p according the old and new maximum values and assigns the new values to 
newp. It is intended to make writing ppm to whatever easier. 

void PPM_DEPTH( pixel newp, pixel p, pixval oldmaxval, pixval newmaxval ) 

This macro determines the luminance of the pixel p: 

float PPM_LUMIN( pixel p ) 

MEMORY MANAGEMENT 

Allocate an array of pixels: 

pixel** ppm_allocarray( int cols, int rows ) 

Allocate a row of thegiven number of pixels 
pixel* ppm_allocrow( int cols ) 

Freethearray allocated with ppm_aiiocarray() containing the given number of rows: 
void ppm_freearray( pixel** pixels, int rows ) 

Free a row of pixels: 

void pbm_freerow( pixel* pixelrow ) 
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READING PBM FILES 

void ppm_readppminit( FILE* fp, int* colsP, int* rowsP, pixval* maxvalP, int* formatP ) 

Read the header from a ppm file, filling in the rows, cols, maxvai, and format variables. 

void ppm_readppmrow( FILE* fp, pixel* pixelrow, int cols, pixval maxvai, int format ) 

Read a row of pixels into the pixelrow array. Format, cols, and maxvai were filled in by ppm readppminito. 
pixel** ppm_readppm( FILE* fp, int* colsP, int* rowsP, pixval* maxvalP ) 

Read an entire pixmap file into memory, returning the allocated array and filling in the rows, cols, and maxvai variables. This 
function combines ppm_readppminit(), ppm_allocarray( ), and ppm_readppmrow(). 

WRITING FILES 

void ppm_writeppminit( FILE* fp, int cols, int rows, pixval maxvai, int forceplain ) 

W rite the header for a portable pixmap file. The forceplain flag forces a plain-format file to be written, as opposed to a raw- 
format one. 

void ppm_writeppmrow( FILE* fp, pixel* pixelrow, int cols, pixval maxvai, int forceplain) 

W rite a row from a portable pixmap. 

void ppm_writeppm( FILE* fp, pixel** pixels, int cols, int rows, pixval maxvai, int force-plain) 

W rite the header and all data for a portable pixmap. This function combi nesppm_writeppminito and ppm_writeppmrow(). 

COLOR NAMES 

T his line parses an ASC11 color name into a pixel: 
pixel ppm_parsecolor( char* colorname, pixval maxvai ) 

The color can be specified in three ways: as a name, assuming that a pointer to an X 11-style color names file was compiled 
in; as an X 11-style hexadecimal number (#rgb, #rrggbb, #rrrgggbbb, or#rrrrggggbbbb); or as a triplet of decimal floating 
point numbers separated by commas (r.r,g.g,b.b). 

This line returns a pointer to a string describing the given color: 
char* ppm_colorname( pixel* colorP, pixval maxvai, int hexok ) 

If the X 11 color names file is available and the color appears in it, that name is returned. Otherwise, if the hexok flag is true, 
then a hexadecimal coiorspec is returned; if hexok is false and the X 11 color names file is avail able, then the closest matching 
color is returned; otherwise it’s an error. 

SEE ALSO 

pbm(3), pgm(3) 

AUTHOR 

Copyright © 1989,1991 by Tony H ansen and Jef Poskanzer 

localeconv 

locaieconv— G ets numeric formatti ng i nformati on 

SYNOPSIS 


#include <locale.h> 

struct lconv *localeconf(void); 
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DESCRIPTION 

The locaieconf o function returns a string to a struct iconv for the current locale. 

C0NF0RMST0 

This command conformsto AN SI C and POSIX.1. 

Linux supports the portable locales C and POSIX and also the European Latin-1 ISO-8859-1, and Russian KOI-8 locales. 
The printf () family of functions may or may not honor the current locale. 

SEE ALSO 

locale(l), localedef(l), strcoll(3), isalpha(3), setlocale(3), strftime(3), locale(7) 

GNU, 25 April 1993 


longj mp 

longjmp — N onlocal jump to a saved stack context 

SYNOPSIS 

#include <setjmp.h> 

void longjmp(jmp_buf env,int val ); 

DESCRIPTION 

longjmpo and setjmp(3) are useful for dealing with errors and interrupts encountered in a low-level subroutine of a program, 
longjmpo restores the environment saved by the last call of setjmpo with the corresponding env argument. After longjmp o is 
completed, program execution continues as if the corresponding call of setjmpo had just returned thevaluevai. longjmpo 
cannot cause 0 to be returned. If longjmp isinvoked with asecond argument of 0 , i will be returned instead. 

RETURN VALUE 

T his function never returns 

CONFORMSTO 

POSIX 

NOTES 

POSIX does not specify if the signal context will be restored or not. If you want to save restore signal masks, use 
sigiongj mp(3). longjmpo makes programshard to understand and maintain. If possible, an alternative should beused. 

SEE ALSO 

setjmp(3), sigsetjmp(2), sigiongjmp(2) 

25 N ovember 1994 


Ifind,lsearch 

ifind, lsearch— Linear search of an array 

SYNOPSIS 


#include <stdlib.h> 

void *lfind(const void *key, const void *base, size t *nmemb, 
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size_t size,int(*compar )(const void *, const void *)); 

void *lsearch(const void *key, const void *base, size_t *nmemb, 

size_t si ze,int(*compar )(const void *, const void *)); 

DESCRIPTION 

ifind() and lsearcho perform a linear search for key in the array base, which has*nmemb elements of size bytes each. The 
comparison function referenced by compar is expected to have two arguments that point to the key object and to an array 
member, in that order, and which returns zero if the key object matches the array member, and non-zero otherwise. 

If lsearcho does not find a matching element, then the key object is inserted at the end of the table, and *nmemb is 
incremented. 

RETURN VALUE 

ifind() returns a pointer to a matching member of the array, or null if no match is found, lsearcho returns a pointer to a 
matching member of the array, or to the newly added member if no match isfound. 

C0NF0RMST0 

SVID 3, BSD 4.3, ISO 9899 

SEE ALSO 

bsearch(3), hsearch(3), tsearch(3) 

GNU, 17 September 1995 


calloc, malloc, free, realloc 

caiioc, maiioc, free, reaiioc— Allocate and free dynamic memory 

SYNOPSIS 

#include <stdlib.h> 

void *calloc(size_t nmemb, size_t size); 

void *malloc(size_t size); 

void free(void *pt r ); 

void *realloc(void *ptr, size_t size); 

DESCRIPTION 

caiioc o allocates memory for an array of nmemb elements of size bytes each and returns a pointer to the allocated memory. 

T he memory is set to zero. 

maiioc o allocates size bytes and returns a pointer to the allocated memory. The memory is not cleared. 

freed frees the memory space pointed to by ptr, which must have been returned by a previous call to maiioc o, caiioc o or 
reaiioc) ). If ptr is null, no operation is performed. 

reaiioc) ) changes the size of the memory block pointed to by ptr to size bytes. The contents will be unchanged to the 
minimum of the old and new sizes; newly allocated memory will be uninitialized. If ptr is null, the call is equivalent to 
maiioc (size); if size is equal to zero, the call is equivalent to free (ptr). Unless ptr is null, it must have been returned by an 
earlier call to malloc)), calloc) ), or realloc)). 

RETURN VALUES 

For caiioc)) and maiioc) ), the value returned is a pointer to the allocated memory, which is suitably aligned for any kind of 
variable, orNULL if the request fails. 

freed returns no value. 
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reaiioco returns a pointer to the newly allocated memory, which is suitably aligned for any kind of variable and may be 
different from ptr, or null if the request fails or if size was equal too. If reaiioco fails, the original block is left untouched; 
it is not freed or moved. 

C0NF0RMST0 

ansi c 


SEE ALSO 

brk(2) 


GNU, 4 April 1993 


mblen 

mbien — D etermines the number of bytes in a character 

SYNOPSIS 

#include <stdlib.h> 

int_mblen(const char *s, size_t n); 

DESCRIPTION 

The mbien o function scans the first n bytes of thestring s and returns the number of bytes in a character. The mbien o 
function is equivalent to 
mbtowc((wchat t*)0,s,n); 

except that theshift state of thembtowco function is not affected. 

RETURN VALUE 

The mbien ((returns the number of bytes in a character, or -i if the character is invalid, or 0 if it is a null string. 

conforms™ 

SVID 3, ISO 9899 

SEE ALSO 

mbstowcs(3), mbtowc(3), wcstombs(3), wctomb(3) 

GNU, 29 March 1993 


mbstowcs 

mbstowcs— C onverts a multi byte string to a wide character string 

SYNOPSIS 

#include <stdlib.h> 

size_t mbstowcs(wchar_t *pwcs, const char *s, size_t n); 

DESCRIPTION 

The mbstowcs 0 function converts a sequence of multi byte characters from the arrays into a sequence of wide characters and 
stores up to n wide characters in the array pwcs. 
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RETURN VALUE 

mbstowcso returns the number of wide characters stored, or -i if s containsan invalid multibyte character. 

C0NF0RMST0 

SVID 3, ISO 9899 

SEE ALSO 

mblen(3), mbtowc(3), wcstombs(3), wctbmb(3) 

GNU, 29 M arch 1993 


mbtowc 

mbtbwc — C onverts a multibyte character to a wide character 

SYNOPSIS 

#include <stdlib.h> 

int mbtowc(wchar_t *pwc, const char *s , size_t n); 

DESCRIPTION 

The mbtowc o function converts a multi byte characters, which isno longer than n bytes, into a wide character and, if pwc is 
not null, stores the wide character in pwc. 

RETURN VALUE 

mbtowc o returnsthe number of bytes in the multi byte character, or -i if the multibyte character isnotvalid. 

C0NF0RMST0 

SVID 3, ISO 9899 

SEE ALSO 

mblen(3), mbstowcs(3), wcstombs(3), wctomb(3) 

GNU, 29 M arch 1993 


memccpy 

memccpy— C opies memory area 

SYNOPSIS 

#include <string.h> 

void *memccpy(void *dest , const void *src,int c, size_t n); 

DESCRIPTION 

The memccpy o function copies no more than n bytes from memory area src to memory area d e s t , stopping when the 
characterc isfound. 

RETURN VALUE 

The memccpy o function returns a pointer to the next character in test after c , or null if c was not found in the first n 
characters of s r c. 
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CONFORMSTO 

SVID 3, BSD 4.3 

SEE ALSO 

bcopy(3), memcpy(3), memmove(3), strcpy(3), strncpy(3) 

GNU, 10 April 1993 


memchr 

memchi— Scans memory for a character 

SYNOPSIS 

#include <string.h> 

void *memchr(const void *s ,int c, size_t n); 

DESCRIPTION 

Thememchro function scans the first n bytes of the memory area pointed to by s for the character c . The first byte to match c 
(interpreted as an unsigned character) stops the operation. 

RETURN VALUE 

Thememchro function returns a pointer to the matching byte or null if the character does not occur in the given memory 
area. 

conforms™ 

SVID 3, BSD 4.3, ISO 9899 

SEE ALSO 

index(3), rindex(3), strchr(3), strpbrk(3), strrchr(3), strsep(3), strspn(3), strstr(3) 

GNU, 12 April 1993 


memcmp 

memcmp— C ompares memory areas 

SYNOPSIS 

#include <string.h> 

int memcmp(const void *sl, const void *s2, size_t n); 

DESCRIPTION 

The memcmp o function compares the first n bytes of the memory areas si and s 2 . It returns an integer less than, equal to, or 
greater than zero if si isfound, respectively, to be less than, to match, or to be greater than s 2 . 

RETURN VALUE 

T he memcmpi ) function returns an integer less than, equal to, or greater than zero if the first n bytes of s l isfound, respec¬ 
tively, to be less than, to match, or be greater than the first n bytes of s 2 . 
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CONFORMSTO 

SVID 3, BSD 4.3, ISO 9899 

SEE ALSO 

bcmp(3), strcasecmp(3), strcmp(3), strcoll(3), strncmp(3), strncasecmp(3) 

10 April 1993 


memcpy 

memcpy— Copies memory area 

SYNOPSIS 

#include <string.h> 

void *memcpy(void *dest , const void *src, size_t n); 

DESCRIPTION 

The memcpy () function copies n bytes from memory area s r c to memory area d e s t . The memory areas may not overlap. U se 
memmove(3) if the memory areas do overlap. 

RETURN VALUE 

Thememcpyo function returns a pointer to dest. 

CONFORMSTO 

SVID 3, BSD 4.3, ISO 9899 

SEE ALSO 

bcopy(3), memccpy(3), memmove(3), strcpy(3), strncpy(3) 

GNU, 10 April 1993 


memfrob 

memf nob— Frobnicates (encrypts) a memory area 

SYNOPSIS 

#include <string.h> 

void *memfrob(void *s, size_t n); 

DESCRIPTION 

T he memf rob o function encrypts the first n bytes of the memory areas by using exclusive or on each character with the 
number 42. The effect can be reversed by using memf rob o on the encrypted memory area. 

Note that thisfunction isnot a proper encryption routine as the xor constant isfixed, and isonly suitablefor hiding strings. 

RETURN VALUE 

T he memf rob o function returns a pointer to theencrypted memory area. 
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CONFORMSTO 

Thememfrobo function isunique to theLinuxC Library and GN U C Library. 

SEE ALSO 

strfry(3) 

GNU, 12 April 1993 


memmem 

memmem — Locates a substring 

SYNOPSIS 

#include <string.h> 

void *memmem(const void *needle, size_t needlelen, 
const void *haystack, size_t haystackl en");" 

DESCRIPTION 

The memmemi ) function fi nds the first occurrence of the substring need i e of length needi el en in the memory area haystack of 
length haystackl en. 

RETURN VALUE 

The memmemo function returns a poi nter to the beginning of the substring, or null if the substring is not found. 

SEE ALSO 

strstr(3) 

GNU, 11 April 1993 


memmove 

memmove— C opies memory area 

SYNOPSIS 

#include <string.h> 

void *memmove(void *dest , const void *src, size_t n); 

DESCRIPTION 

Thememmoveo function copiesn bytes from memory area s r c to memory area d e s t. The memory areasmay overlap. 

RETURN VALUE 

Thememmoveo function returns a pointer to dest. 

conforms™ 

SVID 3, BSD 4.3, ISO 9899 

SEE ALSO 

bcopy(3), memccpy(3), memcpy(3), strcpy(3), strncpy(3) 


GNU, 10 April 1993 
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memset 

memset— Fills memory with a constant byte 

SYNOPSIS 

#include <string.h> 

void *memset(void *s,int c, size_t n); 

DESCRIPTION 

The memset o function fills the first n bytes of the memory area pointed to bes with the constant bytec. 

RETURN VALUE 

The memset o function returns a pointer to the memory areas. 

C0NF0RMST0 

SVID 3, BSD 4.3, ISO 9899 

SEE ALSO 

bzero(3), swab(3) 

GNU, 11 April 1993 


mkfifo 

mkfifo — M akesa FIFO special file (a named pipe) 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/stat.h> 

int mkfifo ( const char *p a th n a me ,mode_t mode ); 

DESCRIPTION 

mkfifo makes a FIFO special file with narnepathname. mode specifies the FIFO's permissions. It is modified by the process's 
umask in the usual way: the permissions of the created file are (mode&umask). 

A FIFO special file is similar to a pipe, except that it is created in a different way. Instead of being an anonymous communi¬ 
cations channel, a FIFO special file is entered into thefilesystem by calling mkfifo. 

After you have created a FIFO special file in this way, any process can open it for reading or writing, in the same way as an 
ordinary file. H owever, it has to be open at both ends simultaneously before you can proceed to do any input or output 
operations on it. 0 pening a FIFO for reading normally blocks until some other process opens the same FIFO for writing, 
and vice versa. 

RETURN VALUE 

Thenormal, successful return valuefrom mkfifo ise. In thecaseof an error, -i isreturned (in which case, errno isset 
appropriately). 

ERRORS 

eacces Oneofthedirectoriesin pathname did notallow search (execute) permission. 

eexist pathname already exists. 
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enametoolong Either the total length of pathname isgreaterthan path_max, or an individual 

filename component has a length greater than name max. In theGN U system, 
thereisno imposed limiton overall filename length, but some filesystems may 
place limits on the length of a component. 

enoent A directory component in pathname does not exist or isa dangling symbolic 

link. 

enospc The directory or filesystem hasno room forthenew file. 

enotdir A component used as a directory in pathname is not, in fact, a directory. 

erofs pathname refersto a read-only filesystem. 

C0NF0RMST0 

POSIX.1 


SEE ALSO 

mkfifo(l), read(2), write(2), open(2), close(2), stat(2), umask(2) 


Linux 1.2.13, 3 September 1995 


mkstemp 

mkstemp — C reates a unique temporary file 

SYNOPSIS 

#include <unistd.h> 

int *mkstemp(char template); 


DESCRIPTION 

The mkstemp o function generates a unique temporary filename from temp! ate. The last six characters of tempi ate must be 
xxxxxx and these are replaced with a string that makes the filename unique. The file is then created with mode read/write and 
permissions 0666. 

RETURN VALUE 

Themkstempo function returns thefile descriptor td of the temporary file. 


ERRORS 

einval The last six characters of tempi ate were not xxxxxx. 

eexist T he temporary file is not unique. 

C0NF0RMST0 

BSD 4.3 

SEE ALSO 

mktemp(3), tmpnam(3), tempnam(3), tmpfile(3) 


GNU, 3 April 1993 


mktemp 

mktemp— M akes a unique temporary filename 
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SYNOPSIS 

#include <unistd.h> 

char *mktemp(char *t empI ate); 

DESCRIPTION 

Themktempo function generates a unique tan poraryfilenamefrom tempi ate. T he last six characters of t empi ate must be 
xxxxxx and these are replaced with a string that makes the filename unique. 

RETURN VALUE 

Themktempo function returns a pointer to temp i ate on success, and null on failure. 

ERRORS 

einval The last six characters of template were not xxxxxx. 

C0NF0RMST0 

BSD 4.3. POSIX dictates tmpnamo. 

SEE ALSO 

mkstemp(3), tmpnam(3), tempnam(3), tmpfile(3) 

GNU, 3 April 1993 
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modf — Extracts signed integral and fractional values from floating-point number 

SYNOPSIS 

#include <math.h> 

double modf (double x, double *iptr); 

DESCRIPTION 

T he modf o function breaks the argument x into an integral part and afractional part, each of which has the same sign asx. 
Theintegral part is stored in i ptr. 

RETURN VALUE 

T he modf o function returns the fractional part ofx. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

frexp(3), ldexp(3) 
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asctime,ctime, difftime, gmtime, localtime, mktime 

asctime, ctime, diff time, gmtime, localtime, mktime —Convert date andtimetO ASCII 



asctime, dime, difftime, gmtime localtime mktime 


SYNOPSIS 

extern char *tzname[ 2 ]; 

void tzset() 

#include <sys/types.h> 

char *ctime(clock) 
const time_t ‘clock; 

double difftime(timel, time 0 ) 
time_t timel; 
time_t time 0 ; 

#include <time.h> 

char *asctime(tm) 
const struct tm *tm; 

struct tm *localtime(clock) 
const time_t ‘clock; 

struct tm ‘gmtime(clock) 
const time_t ‘clock; 

time_t mktime(tm) 
struct tm *tm; 

cc ... -lz 

DESCRIPTION 

ctime converts a long integer, pointed to by clock, representing the time in seconds since 00:00:00 UTC, January 1,1970, 
and returns a pointer to a 26-character string of the form Thu Nov 24 18:22:48 1986. (N ote: UTC is Coordinated Universal 
Time.) All the fields have constant width. 

localtime and gmtime return pointers to tm structures, described in the foil owing paragraphs, locaitime corrects for the time 
zone and any time zone adjustments (such as Daylight Saving Time in the United States). Before doing so, locaitime calls 
tzset (if tzset has not been called in the current process). After filling in thetm structure, locaitime sets the tm_isdst'th 
element of tzname to a pointer to an ASCII string that's the time zone abbreviation to be used with locaitime 's return value. 

gmtime converts to C oord in ated Universal Time. 

asctime converts a time value contained in a tm structure to a 26-character string, as shown in the preceding example, and 
returns a pointer to the string. 

mktime converts the broken-down time, expressed as local time, in the structure pointed to by tm into a calendar time value 
with the same encoding as that of the values returned by the time function. The original values of the tm_wday and tm_yday 
components of the structure are ignored, and the original values of the other components are not restricted to their normal 
ranges. (A positive or zero value for tm_isdst causes mktime to presume initially that summer time (for example, Daylight 
Saving Time in the United States) respectively, is or is not in effect for the specified time A negative value for tm_isdst 
causes the mktime function to attempt to divine whether summer time is in effect for the specified time.) On successful 
completion, the values of the tm_wday and tm_yday components of the structure are set appropriately, and the other 
components are set to represent the specified calendar time, but with their values forced to their normal ranges; the final 
value of tm_mday is not set until tm_mon and tm_year are determined, mktime returns the specified calendar time; if the calendar 
ti me cannot be represented, it returns - 1 . 
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difftime returnsthedifference between two calendar times, (ti mei - ti meo), expressed in seconds. 

Declarations of all the functions and externals, and thetm structure, arein the <time.h> header file. The structure (of type) 
struct tm includesthefollowingfields: 

int tm_sec; / seconds (0 - 60) / 

int tm_min; / minutes (0 - 59) / 

int tm_hour; / hours (0 - 23) / 

int tm_mday; / day of month (1 -31) / 

int tm_mon; / month of year (0 - 11) / 

int tm_year; / year - 1900 / 

int tm_wday; / day of week (Sunday = 0) / 

int tm_yday; / day of year (0 - 365) / 

int tm_isdst; / is summer time in effect? / 

char tm_zone; / abbreviation of timezone name / 

long tm_gmtoff; / offset from UTC in seconds / 

T he tm_zone and tm_gmtoff fields exist, and are filled in, only if arrangements to do so were made when the library containing 
these functions was created. There is no guarantee that these fields will continue to exist in this form in future releases of this 
code. 

Tm_isdst is non-zero if summer time is in effect. 

Tm_gmtoff is the offset (in seconds) of the time represented from UTC, with positive values indicating east of the Prime 
M eridian. 

FILES 

/usr/local/etc/zoneinfo Timezone information directory 

/usr/local/etc/zoneinfo/localtime Local timezonefile 

/usr/local/etc/zoneinfo/posixrules Used with PO SIX-StyleTZS 

/usr/iocai/etc/zoneinfo/GMT For UTC leap seconds 

If /usr/local/etc/zoneinfo/GMT is absent, UTC leap seconds are loaded from /usr/local/etc/zoneinfo/posixrules. 

SEE ALSO 

getenv(3), newtzset(3), time(2), tzfile(5) 

NOTES 

The return values point to static data; the data is overwritten by each call. The tm_zone field of a returned struct tm points to 
a static array of characters, which will also be overwritten at the next call (and by cal Is to tzset). 

Avoid using out-of-range values with mktimewhen settingup lunch with promptness sticklers in Riyadh. 

tzset 

tzset— Initializes time conversion information 

SYNOPSIS 



void tzset(); 
cc ... -lz 
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tZSZt 


DESCRIPTION 

tzset uses the value of the environment variable tz to set time conversion information used by locaitime.lf tz does not 
appear in the environment, the best available approximation to local wall clock time, as specified by thetzfiie(5)-format file 
localtime in the system time conversion information directory, is used by locaitime. If tz appears in the environment but its 
value is a null string, Coordinated Universal Time(UTC) is used (without leap second correction). If tz appears in the 
environment and its value is not a null string, itisused in oneof thefollowingways: 

If the value begins with a colon, it is used as a pathname of a file from which to read the time conversion information. 

If the value does not begin with a colon, it is first used as the pathname of a file from which to read the time conversion 
information, and, if that file cannot be read, is used directly as a specification of the time conversion information. 

When tz is used as a pathname if it begins with a slash, itisused as an absolute pathname; otherwise, it is used as a 
pathname relative to a system time conversion information directory. The file must be in theformat specified in tztiie(5). 

When tz isused directly as a specification of thetime conversion information, it must havethefollowing syntax (spaces 
inserted for clarity): 

st d of f set [ ds t [ of f set ] [, r uI e] ] 

T he elements are as follows: 

st d and d st Three or more bytes that are the designation for the standard ($td) or 

summer (dst) timezone. Onlystd isrequired; if ds t ismissing, then 
summer time does not apply in this locale. Uppercase and lowercase 
letters are explicitly allowed. Any characters except a leading colon (:), 
digits, comma (,), minus (-), plus (+), and ASCII N U L are allowed, 
offset Indicates the value one must add to thelocal time to arrive at 

Coordinated Universal Time T heof f set has the form: 
h h[:mm[:s s]] 

The minutes (mm) and seconds (ss) are optional. The hour (hh) isrequired 
and may be a single digit. T he of f s et followi ng s t d isrequired. If no 
offset follows dst, summer time is assumed to be one hour ahead of 
standard time. 0 ne or more digits may be used; the value is always 
interpreted as a decimal number. T he hour must be between zero and 24, 
and the minutes (and seconds)— if present— between zero and 59. If 
preceded by a ■+■, the time zone shall be east of the Prime M eridian; 
otherwise, it shall be west (which may be indicated by an optional 
preceding"-“). 

rule Indicates when to change to and back from summertime. T he r ui e has 

the form: 

d a t e /t i me, d a t e /t i me 

where the first date describeswhen thechangefrom standard to summer 
time occurs and the second date describeswhen the change back happens. 
Each ti me field describeswhen, in current local time, thechangeto the 
other time is made. 

Theformat of date is one of the following: 

T he d 'th day (0 <=d <=6) of week n of month m of the year (1 <=n 
<=5,1 <=m <=12, where week 5 means "the last d day in month m" 
which may occur in either the fourth or the fifth week). Week 1 
is the first week in which thed 'th day occurs Day zero is Sunday, 
jn The Julian day n (1 <=n <= 365). Leap days are not counted; that is, in 

all years- including leap years— February 28 is day 59 and M arch 1 is 
day 60. It is impossible to explicitly refer to the occasional February 29. 
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The zero-based Julian day (0 <=n <= 365). Leap days are counted, and it 
ispossibleto refer to February 29. 

Thed'th day (0 <=d <=6) of week n of month m of the year (1 <=n <=5, 
1 <=m <=12, where week 5 means "the last d day in month m,” which 
may occur in either the fourth or the fifth week). Week 1 is the first week 
in which thed'th day occurs. Day zero is Sunday. 

The time has the same format as offset except that no leading sign ("+" 
or is allowed. T he default, if time is not given, is 02:00:00. 

If no rule is present in tz, the rules specified by thetzfiie(5)-formatfileposixruies in the system time conversion 
information directory are used, with the standard and summer time offsets from UTC replaced by those specified by the 
offset values in tz. 

For compatibility with System V Release 3.1, a semicolon (;) may be used to separate the rule from the rest of the specifica¬ 
tion. 

If the tz environment variable does not specify a tzfiie(5)-format and cannot be interpreted as a direct specification, UTC is 
used. 


n 

Mm. n, d 


FILES 

/usr/local/etc/zoneinfo 
/usr/local/etc/zoneinfo/localtime 
/usr/local/etc/zoneinfo/posixrules 
/usr/local/etc/zoneinfo/GMT 


Timezoneinformation directory 
Local timezonefile 
Used with POSIX-style tzs 
For UTC leap seconds 


If /usr/local/etc/zoneinfo/GMT is absent, UTC leap seconds are loaded from / usr / local/etc/zoneinfo/posixrules. 


SEE ALSO 

getenv(3), newctime(3), time(2), tzfile(5) 


on_exit 

on exit— Registers a function to be called at normal program termination 

SYNOPSIS 

#include <stdlib.h> 

int on_exit(void (*function)(int , void *), void *arg); 

DESCRIPTION 

T he on_exit () function registers the given function to be called at normal program termination, whether via exit(2) or via 
return from the program's main. The function is passed the argument to exit(3) and thearg argument from on_exit(). 

RETURN VALUE 

T he on_exit () function returns the value 0 if successful; otherwise, the value -1 isreturned. 

SEE ALSO 

exit(3), atexit(3) 
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opendir 

opendir— 0 pens a di rectory 

SYNOPSIS 

#include <sys/types.h> 

#include <dirent.h> 

DIR *opendir(const char *na me); 

DESCRIPTION 

Theopendirf) function opens a directory stream corresponding to the directory name, and returns a pointer to the directory 
stream. The stream is positioned at the first entry in the directory. 

RETURN VALUE 

Theopendir-o function returns a pointer to the directory stream or null if an error occurred. 

ERRORS 


EACESS 

Permission denied 

EMFILE 

T oo many file descriptors in use by process 

ENFILE 

T oo many files are currently open in the system 

ENOENT 

Directory does not exist, orname isan empty string 

ENOMEM 

Insufficient memory to complete the operation 

ENOTDIR 

name is not a directory 


C0NF0RMST0 

SVID 3, POSIX, BSD 4.3 

SEE ALSO 

open(2), readdir(3), closedir(3), rewinddir(3), seekdir(3), telldir(3), scandir(3) 

11 Junel995 

parsedate 

parsedate— Converts time and date string to number 

SYNOPSIS 

#include <sys/types.h> 
typedef struct_TIMEINFO f 
time; 

long usee; 
long tzone; 

} TIMEINFO; 
time_t 

parsedate(text, now) 
char *text; 

TIMEINFO *now; 

DESCRIPTION 

parsedate converts many common time specifications into the number of seconds si nee the epoch, that is, atime_t; see 

time(2). 
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parsedate returns the time, or -i on error, text is a character string containing the time and date, now is a pointer to the time 
that should be used for calculating relative dates. If now is null, then GetTimeinfo in i±binn(3) is used to obtain the current 
timeand timezone. 

T he character string consists of zero or more specifications of the following form: 

time A time Of day, which is Of the form hh[:mm[:ss ]] [meri di an][zone]Orhhmm 

[meri di an ] [zone ]. If no meridian is specified, hh is interpreted on a 24-hour 
clock. 

date A specific month and day with optional year. T he acceptable formats are 

mm/dd [ / yy ], yyyy/ mm /dd, monthname d d [, y y ], d d mo n t h n a me [y y ], and 
day.ddmonthnameyy, and day, dd monthname yy . T he default year i S th e Current 
year. If the year is less then 100, then 1900 is added to it; if it is I ess then 21, 
then 2000 is added to it. 

relative time A specification relative to the current time. T he format isnu mber unit; 

acceptable units are year, month, week, day, hour, minute (or min), and second 
(or sec). T he unit can be specified as a singular or plural, as in 3 weeks. 

The actual date is calculated according to the following steps. First, any absolute date or time is processed and converted. 
Using that time as the base, day-of-week specifications are added. N ext, relative specifications are used. If a date or day is 
specified, and no absolute or relative time is given, midnight is used. Finally, a correction is applied so that the correct hour 
of the day is produced after allowi ng for D ayli ght Savi ngs T i me differences. 

parsedate ignores case when parsing all words; unknown words are taken to beunknown time zones, which are treated as 
GMT. The names of the months and daysoftheweek can be abbreviated to their first three letters, with optional trailing 
period. Periods are ignored in any time zone or meridian values. 

BUGS 

parsedate does not accept all desirable and unambiguous constructions. Semantically incorrect dates such as "February 31" 
are accepted. 

Daylight Savi ngs Time is always taken as a one-hour change that is wrong for some places. The Daylight Savi ngs Time 
correction can get confused if parsing a time within an hour of when the reckoning changes, or if given a partial date. 

HISTORY 

Originally written by Steven M . Bellovin (smb@research.att.com) while at the U niversity of N orth Carolina at Chapel H ill 
and distributed under the name getdate. 

A major overhaul was done by Rich $alz (rsaiz@bbn.com) and Jim Berets (jberets@bbn.com) in August, 1990. 

It was further revised (primarily to remove obsolete constructs and timezone names) a year later by Rich (now 
rsaiz@osf.org) for I nterN etN ews, and the name was changed. 

SEE ALSO 

date(l), ctime(3), libinn(3), time(2) 

perror 

perror— Prints a system error message 

SYNOPSIS 

#include <stdio.h> 

void perror(const char *s); 



#include <errno.h> 
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const char *sys_errlist[]; 
int sys_nerr; 

DESCRIPTION 

The routine pemoro produces a message on the standard error output, describing the last error encountered during a call to 
a system or library function. The argument string s isprinted first, then a colon and a blank, then the message and a newline. 
To be of most use, the argument string should include the name of the function that incurred the error. The error number is 
taken from the external variable e r r no, which is set when errors occur but not cleared when nonerroneous calls are made. 

The global error list sys_erriist[] indexed by err no can be used to obtain the error message without the newline The largest 
message number provided in the table is sys_nerr -i. Be careful when directly accessing this list because new error values 
may not have been added to sys_erriist[]. 

When a system call fails, it usually returns -i and sets the variable err no to a value describing what went wrong. (These values 
can be found in <errno.h>.) M any library functions do likewise. The function perroro serves to translate this error code into 
human-readable form. N ote that err no is undefined after a successful library call. This call may well change this variable 
even though it succeeds, for example, because it internally used some other library function that failed. Thus, if a failing call 
is not immediately followed byacall to perror, the value of errno should be saved. 

C0NF0RMST0 

ANSI C, BSD 4.3, PO SIX, X/O PEN 

SEE ALSO 

strerror(3) 

16 May 1996 


popen,pclose 

popen, pclose— Process I/O 

SYNOPSIS 

#include <stdio.h> 

FILE *popen(const char *command, const char *type); 
int pclose(FILE *st ream); 

DESCRIPTION 

T he popeno function opens a process by creating a pipe, forking, and invoking the shell. Because a pipe is by definition 
unidirectional, thetype argument may specify only reading or writing, not both; the resulting stream is correspondingly 
read-only or write-only. 

The command argument is a pointer to a null-terminated string containing a shell command line. This command is passed to 
/bin/sh using the -c flag; interpretation, if any, isperformed by the shell. Themode argument is a pointer to a null- 
terminated string which must be either r for reading or w for writing. 

The return value from popen o is a normal standard I/O stream in all respects save that it must be closed with pclose o rather 
than f close o. W ri ting to such a stream writes to the standard input of the command; the command's standard output is the 
same as that of the process that called popeno, unless thisisaltered bythecommand itself. Conversely, reading from a 
"popened" stream reads the command's standard output, and the command's standard input is the same as that of the 
process that called popen. 
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N otethat output popen streams are fully buffered by default. 

Thepciose function waits for the associated process to terminate and returns the exit status of the command as returned by 

wait4. 

RETURN VALUE 

The popen function returns null if the fork(2) or pipe(2) cal Is fail, or if it cannot allocate memory. 

Thepciose function returns-i if stream is not associated with a"popened" command, if stream already "pclosed," or if wait4 
returns an error. 

ERRORS 

The popen function does not reliably set err no. (Is this true for Linux?) 

BUGS 

The standard input of a command opened for reading shares its seek offset with the process that called popeno; therefore, if 
the original process has done a buffered read, the command's input position may not be as expected. Similarly, the output 
from a command opened for writing may become intermingled with that of the original process. The latter can be avoided 
by calling ffiush(3) before popen. 

Failure to execute the shell is indistinguishable from the shell's failure to execute command, or an immediate exit of the 
command. The only hint is an exit status of 127. (Is this true under Linux?) 

Thefunction popeno always calls sh, never calls csh. 

HISTORY 

A popeno and a pcioseo function appeared in Version 7 AT&T U NIX. 

SEE ALSO 

fork(2), sh(l), pipe(2), wait4(2), fflush(3), fclose(3), fopen(3), stdio(3), system(3), fclose(3), fopen(3), stdio(3), system(3). 
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printf, fprintf, sprintf,snprintf,vprintf,vfprintf, 
vsprintf,vsnprintf 

printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, vsnprintf — Formatted Output conversion 

SYNOPSIS 

#include <stdio.h> 

int printf( const char *format, ...); 

int fprintf( FILE *s t ream, const char *format, ...); 

int sprintf( char *str, const char *format, . ..); 

int snprintf( char *str, size_t size, const char *format, ...); 

#include <stdarg.h> 

int vprintf( const char *for mat ,va_list ap); 

ant vfprintf( FILE *s t ream, const char *format ,va_list ap); 

int vsprintf( char *str, char *format, va_list ap); 

int vsnprintf ( char *str, size_t size, char *f or mat ,va_list ap); 
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DESCRIPTION 

The printf family of functions produces output according to a for mat, as described in the following paragraphs. The 
functions printf and vprintf write output to stdout, the standard output stream; fprintf and vfprintf write output to the 
given output s t ream; sprintf, snprintf, vsprintf, and vsnprintf write to the character string s t r. 

These functions write the output under the control of a for mat string that specifies how subsequent arguments (or arguments 
accessed via the variable-length argument facilities of stdarg(3)) are converted for output. 

These functions return the number of characters printed (not including the trailing \e used to end output to strings), 
snprintf and vsnprintf do not write more than s'zebytes (including thetrailing \e), and return -i if the output was 
truncated due to thislimit. 

T he f or mat string is composed of zero or more directives: ordinary characters (not %), which are copied unchanged to the 
output stream; and conversion specifications, each of which results in fetching zero or more subsequent arguments. Each 
conversion specification isintroduced by the character %. The arguments must correspond properly (after type promotion) 
with theconversion specifier. After the%, zero or more of the followi ng flags appear in sequence: 

# Specifying that the value should be converted to an alternate form. Fore, d, i, n, p, s, and u 

conversions, thisoption has no effect. Foro conversions, the precision of thenumber isincreased to 
force the first character of the output string to a zero (except if a zero value is printed with an explicit 
precision of zero). For x and x conversions a non-zero result has the string ex (or ex for x 
conversions) prepended to it. Fore, e, f, g, and g conversions, the result will always contain a decimal 
point, a/en if no digits follow it (normally, adecimal point appears in the results of those conversions 
only if a digit follows). For g and g conversions, trailing zeros are not removed from the result as they 
would otherwise be. 

e Specifying zero padding. For all conversions except n, the converted value is padded on the left with 

zeros rather than blanks. If a precision is given with a numeric conversion (d, i, o, u, i, x, and x), the 
0 flag is ignored. 

(a negative field width flag) Indicates the converted value is to be left adjusted on the field boundary. 
Except for n conversions the converted value is padded on the right with blanks rather than on the 
left with blanks or zeros. A - overrides a e if both are given. 

1 1 (a space) Specifying that a blank should be left before a positive number produced by a signed 

conversion (d, e, e, f, g, g, or i). 

+ Specifying that a sign always be placed before a number produced by a signed conversion. 

A + overrides a space if both are used. 

1 Specifying that in a numerical argument the output isto be grouped if the locale information 

indicates any. N otethat many versions of gcc cannot parse this option and will issue a warning. 

An optional decimal digit string specifying a mini mum field width. If the converted value has fewer 
characters than thefield width, it will be padded with spaces on the left (or right, if the left- 
adjustment flag has been given) to fill out thefield width. 

An optional precision, in the form of a period (.) followed by an optional digit string. If the digit 
string is omitted, the precision is taken as zero. This gives the minimum number of digits to appear 
ford, i, o, u, x, and x conversions; thenumber of digits to appear after the decimal point for e, e, and 
t conversions; the maximum number of significant digits for g and g conversions; or the maximum 
number of characters to be printed from a string for s conversions. 

The optional character h, specifying that a following d, i, o, u, x, or x conversion corresponds to a 
short int or unsigned short mt argument, or that a following n conversion corresponds to a pointer 
to a short int argument. 

The optional character l (ell) specifying that a following d, i, o, u, x, or x conversion applies to a 
pointer to along int or unsigned long int argument, or that a following n conversion corresponds to 
a pointer to a long mt argument. Linux provides a non-AN SI-compliant use of two l flags as a 
synonym to q or l. Thus, n can be used in combination with float conversions. This usage is 
however, strongly discouraged. 
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The character l specifying that a following e, e, f, g, or g conversion corresponds to along double 
argument, or a following d, i, o, u, x, or x conversion corresponds to along long argument. N otethat 
long long is not specified in AN SI C and therefore not portable to all architectures. 

Theoptional character q. T his is equivalent to l. See the "Standards" and "Bugs" sectionsfor 
comments on the use of 11, l, and q. 

A z character specifying that the following integer (d, i, o, u, i, x, and x) conversion corresponds to a 
size_t argument. 

A character that specifies the type of conversion to be applied. 

A field width or precision, or both, may be indicated by an asterisk * instead of a digit string. In thiscase, an mt argument 
supplies thefi eld width or precision. A negative field width istreated as a left adjustment flag followed by a positive field 
width; a negative precision istreated as though it were missing. 

Theconversion specifiers and their meanings are as follows: 

diouxx Theint (or appropriate variant) argument is converted to signed decimal (d and i), 

unsigned octal (o), unsigned decimal (u), or unsigned hexadecimal (x and x) notation. The 
letters abcdef are used forx conversions; the letters abcdef areused for x conversions. The 
precision, if any, gives theminimum number of digits that must appear; if the converted 
value requires fewer digits, it is padded on the left with zeros. 

eE The double argument isrounded and converted in the style [-]d.ddde\dd where there is 

one digit before the decimal-point character and the number of digits after it is equal 
to the precision; if the precision ismissing, itistaken as6; if the precision iszero, no 
decimal-point character appears. An e conversion uses the letter e (rather than e) to 
introduce the exponent. The exponent always contains at least two digits; if thevalueis 
zero, the exponent is 00. 

f The double argument isrounded and converted to decimal notation in the style 

[ - ]ddd. ddd , where the number of digits after the decimal-point character is equal to 
the precision specification. If the precision ismissing, itistaken as6; if the precision is 
explicitly zero, no decimal-point character appears. If a decimal point appears, at least one 
digit appears before it. 

g The double argument isconverted in stylet ore (or e for g conversions). The precision 

specifies the number of significant digits. If the precision ismissing, 6 digits are given; if 
the precision iszero, it istreated asl. Style e isused if the exponent from its conversion is 
less than negative4 or greater than or equal to the precision. Trailing zeros are removed 
from thefractional part of the result; a decimal point appears only if it isfollowed by at 
least onedigit. 

c Theint argument isconverted to an unsigned chan, and the resulting character is written. 

s T he chan * argument is expected to be a pointer to an array of character type (pointer to a 

string). Characters from the array are written up to (but not including) a terminating nul 
character; if a precision is specified, no more than the number specified are written. If a 
precision isgiven, no null character need be present; if the precision isnot specified, oris 
greater than the size of the array, the array must contain a terminating nul character. 

p The void * pointer argument is printed in hexadecimal (as if by %#x or %#ix). 

n The number of characters written so far is stored into the integer indicated by theint * 

(or variant) pointer argument. N o argument is converted. 

% A % is written. N o argument isconverted. The complete conversion specification is%%. 

In no case does a nonexistent or small field width cause truncation of afield; if the result of a conversion is wider than the 
field width, thefi eld isexpanded to contain theconversion result. 



printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, vsnprintf 



EXAMPLES 

T o print a date and time in the form "Sunday, July 3,10:02,” where weekday and month are pointers to strings: 

#include <stdio.h> 

fprintf(stdout, "%s, %s %d, %.2d:%.2d\n", 
weekday, month, day, hour, min); 

To print to five decimal places: 

#include <math.h> 

#include <stdio.h> 

fprintf(stdout, "pi = %.5f\n", 4 * atan(1.0)); 

T o allocate a 128-byte string and print into it: 

#include <stdio.h> 

#include <stdlib.h> 

#include <stdarg.h> 

char *newfmt(const char *fmt, ...) 

{ 

char *p; 
va_list ap; 

if ((p = malloc(128)) == NULL) 
return (NULL); 
va_start(ap, fmt); 

(void) vsnprintf(p, 128, fmt, ap); 
va_end(ap); 
return (p); 

} 

SEE ALSO 

printf(l), scanf(3) 

STANDARDS 

T he fprintf, printf, sprintf, vprintf, vfprintf, and vsprintf functions conform to AN SI C 3.159-1989 ("AN SI C ”). 

Theq flag is the BSD 4.4 notation for long long, while 11 or the usage of l in integer conversions is theGN U notation. 

The Linux version of these functions is based on theGN U libio library. T akea look at the info documentation of GN U 
iibc (glibc-1.08) for a more concise description. 

BUGS 

Somefloating point conversions under Linux cause memory leaks. 

All functions are fully AN SI C 3.159-1989 conformant, but provide the additional flags q, z, and 1 aswell as an additional 
behavior of the l and l flags. The latter may be considered to be a bug, as it changes the behavior of flags defined in AN SI 
C 3.159-1989. 

The effect of padding the %p format with zeros (either by the 0 flag or by specifying a precision), and the benign effect (that 
is, none) of the# flag on %n and %p conversions, aswell as nonsensical combi nations that are not standard; such combinations 
should be avoided. 

Some combinations of flags defined by AN SI C are not making sense (for example, %m). While they may have a well-defined 
behavior on Linux, this need not to be so on other architectures. Therefore, it usually is better not to use flags that are not 
defined by AN SI C at all; in other words, that use g instead of l in combination with diouxx conversions or 11 . 

T he usage of q is not the same as on BSD 4.4, as it may be used in float conversions equivalently to l. 
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Because sprintf and vsprintf assume an infinitely long string, callers must be careful not to overflow the actual space; this is 
often impossible to assure. 

Linux man page; 28 January 1996 


psignal 

psignai— Prints signal message 

SYNOPSIS 

#include <signal.h> 

void psignal(int sig, const char *s); 

extern const char *const sys si glist [] 


DESCRIPTION 

The psignai o function displays a message on stderr consisting of the string s, a colon, a space, and a string describing the 
signal number sig. If sig is invalid, the message displayed will indicate an unknown signal. 

The array sys sigiist holds the signal description strings indexed by signal number. 

RETURN VALUE 

The psignai o function returns no value. 

C0NF0RMST0 

BSD 4.3 


SEE ALSO 

perror(3), strsignal(3) 


GNU, 13 April 1993 


putenv 

putenv— Changes or adds an environment variable 

SYNOPSIS 

#include <stdlib.h> 

int putenv(const char *string); 

DESCRIPTION 

T he putenv < > function adds or changes the value of environment variables. The argument string is of the form name = value. 
If name does not already exist in the environment, then string isadded to theenvironment. If name does exist, then the value 
of name in the environment is changed to va i ue. 

RETURN VALUE 

T he putenv <) function returnszero on success, or-i if an error occurs 

ERRORS 


ENOMEM 


Insufficient space to allocate new environment 



fputc fputs putc, putchar, puts 


997 


CONFORMSTO 

SVID 3, POSIX, BSD 4.3 

SEE ALSO 

getenv(3), setenv(3), unsetenv(3) 

GNU, 8 April 1993 


putpwent 

putpwent—W rites a password file entry 

SYNOPSIS 

#include <pwd.h> 

#include <stdio.h> 

#include <sys/types.h> 

int putpwent(const struct passwd * p,FILE*stream); 

DESCRIPTION 

The putpwent o function writes a password entry from the structure p in the file associated with stream. 
T he passwd structure is defined in <pwd.h> as follows: 

struct passwd { 


char 

*pw_name; 

/* user name */ 

char 

*pw_passwd; 

/* user password */ 

uid_t 

pw_uid; 

/* user id */ 

gid_t 

pw_gid; 

/* group id */ 

char 

*pw_gecos; 

/* real name */ 

char 

*pw_dir; 

/* home directory * 

char 

*pw_shell; 

1 * shell program */ 


}; 


RETURN VALUE 

The putpwent o function returns 0 on success, or -1 if an error occurs. 

ERRORS 

einval Invalid (null) argument given 

conforms™ 

svid 3 

SEE ALSO 

fgetpwent(3), getpwent(3), setpwent(3), endpwent(3), getpwnam(3), getpwuid(3), getpw(3) 


GNU, 9 April 1993 


fputc, fputs, putc, putchar, puts 

fputc, fputs, putc, putchar, puts— Output of characters and strings 
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SYNOPSIS 

#include <stdio.h> 

int fputc(int c,FILE*strearn); 

int fputs(const char *s ,FILE*st r earn); 

int putc(int c ,FILE *s t r eam); 

int putchar(int c); 

int puts(char *s); 

int ungetc(int c,FILE *stream); 

DESCRIPTION 

fputco writes the character c, cast to an unsigned char, to stream, 
fputso writes the string s to stream, without its trailing \o. 

putc () is equivalent to fputco except that it may be implemented as a macro that evaluates stream more than once. 

putchar(c >; is equivalent to putc(c.stdout). 

putso writes the string s and a trailing newlineto stdout. 

Calls to the functions described here can be mixed with each other and with calls to other output functions from thestdio 
library for the same output stream. 

RETURN VALUES 

fputco, putco, and putcharo return the character written as an unsigned char cast to an int or eof on error, 
putso and fputso return a non-negative number on success, or eof on error. 

C0NF0RMST0 

ANSI C, POSIX.1 

BUGS 

It is not advisable to mix cal Is to output functions from thestdio library with low-level cal Is to write o for the file descriptor 
associated with the same output stream; the results will be undefined and very probably not what you want. 

SEE ALSO 

write(2), fopen(3), fwrite(3), scanf(3), gets(3), fseek(3), ferror(3) 

GNU, 4 April 1993 


qio 

qio— Q uick I/O part of I nterN etN ews li brary 

SYNOPSIS 

#include "qio.h" 

QIOSTATE * 

QIOopen(name, size) 
char *name; 
int size; 

QIOSTATE * Q10fdopen(fd, size) 

int fd; 

int size; 

void QlOclose(qp) 

QIOSTATE *qp; 



char * QlOread(qp) 

QIOSTATE *qp; 
int QlOlength(qp) 

QIOSTATE *qp; 
int QlOtoolong(qp) 

QIOSTATE *qp; 
int QlOerror(qp) 

QIOSTATE *qp; 
int QlOtell(qp) 

QIOSTATE *qp; 
int QlOrewind(qp) 

QIOSTATE *qp; 
int QlOfileno(qp) 

QIOSTATE *qp; 

DESCRIPTION 

The routines described in this manual page are part of the I nterN etN ews library, iibinn(3). They are used to provide quick 
read access to files. The letters qio stand for Quick I/O. 

Qioopen opens the file n a me for reading. It uses a buffer of size bytes, which must also be larger then the longest expected line. 
T he header file defines the constant qio_buffer as a reasonable default. If size is zero, then Qioopen will call stat(2) and use 
the returned block size; if that fails it will useoio^BUFFER. It returns null on error, or a pointer to a handle to be used in other 
calls Qiofdopen performs the samefunction except that td refers to an already-open descriptor. 

Qiociose closes the open file and releases any resources used by it. 

Qioread returns a pointer to the next line in the file. The trailing newline will be replaced with a\o. If eof is reached, an error 
occurs, or if the line is longer than the buffer, Qioread returns null. 

After a successful call to Qioread, Qioiength will return the length of the current line. 

The functions Qiotooiong and Qioemor can be called after Qioread returns null to determine if there was an error, or if the 
linewastoo long. If Qiotooiong returns non-zero, then the current line did not fit in the buffer, and the next call to Qioread 
will try read the rest of the line. Long lines can only be discarded. If Qioerror returns non-zero, then a serious I/O error 
occurred. 

Qioteii returns the iseek(2) offset at which the next linewill start. 

Qiorewind sets the read pointer back to the beginning of the file 
Qiofiieno returns the descriptor of the open file. 

Qioiength, Qiotooiong, Qioerror, Qioteii, and Qiofiieno are implemented as macros defined in the header file. 

EXAMPLE 

QIOSTATE *h; 
long offset; 
char *p; 

h = QlOopenC'/etc/motd 11 , QIO_BUFFER); 

for (offset = Qioteii(h); (p = QlOread(h)) != NULL; offset = QlOtell(h)) 
printfC'At %ld, %s\n“, offset, p); 
if (QlOerror(h)) { 

perror(“Read error"); 
exit(1); 

} 

QlOclose(h); 

HISTORY 

W ritten by Rich $alz (rsaiz@uunet.uu.net) for I nterN etN ews. 
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qsort 

qsort— Sorts an array 

SYNOPSIS 

#include <stdlib.h> 

void qsort(void *base, size_t nmemb, size_t size,int(*compar ) 

(const void *, const void *)); 

DESCRIPTION 

The qsort o function sorts an array with nmemb el ementsof sizes i ze.' The base argument points to the start of the array. 

The contents of the array are sorted in ascending order according to a comparison function pointed to by compar, which is 
called with two arguments that point to the objects being compared. 

The comparison function must return an integer less than, equal to, or greater than zero if the first argument is considered to 
be respectively less than, equal to, or greater than the second. If two members compare as equal, their order in the sorted 
array isundefined. 

RETURN VALUE 

The qsort o function returns no value. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 


sort(1) 

GNU, 29 March 1993 


raise 

raise— Sends a signal to the current process 

SYNOPSIS 

#include <signal.h> 
int raise (int si g); 

DESCRIPTION 

T he raise function sends a signal to the current process. It is equivalent to 

kill(getpid() ,si g) 

RETURN VALUE 

Zero on success, non-zero for failure. 

C0NF0RMST0 

ANSI C 

SEE ALSO 

kill(2), signal(2), getpid(2) 


GNU, 31 August 1995 
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rand, srand 

rand, srand— Random number generator 

SYNOPSIS 

#include <stdlib.h> 
int rand(void); 

void srand(unsigned int seed); 

DESCRIPTION 

T he rando function returns a pseudo-random integer between 0 and rand_max. 

T he srand0 function sets its argument as the seed for a new sequence of pseudo-random integers to be returned by rand(). 
These sequences are repeatable by calling srand 0 with thesameseed value. 

If no seed value is provided, the rand 0 function is automatically seeded with a value of 1 . 

RETURN VALUE 

The rando function returns a value between 0 and rand_max. The srand 0 returns no value. 

NOTES 

The versions of rando and srando in the Linux C Library use thesamerandom number generator as random 0 and 
srandomo, so the lower-order bits should be as random as the higher-order bits. H owever, on older rando implementations, 
the lower-order bitsaremuch less random than the higher-order bits 

In Numerical Recipes in C: T he Art of Scientific Computing (W illiam H. Press, Brian P. Flannery, Saul A. T eukolsky, William 
T. Vetterling; N ew York: CambridgeU niversity Press, 1990, first ed, p. 207), the foil owing comments are made: 

"If you want to generate a random integer between 1 and 10, you should always do it by 
j =1 + (int) (10.0*randO / (RAND+MAX+1.0)); 
and never by anything resembling 

j=1+((int) (1000000.0*rand()) % 10); 

(which uses lower-order bits).'' 

Random-number generation isacomplextopic. TheNumericai Recipes in c book (seepreceding reference) provides an 
excellent discussion of practical random-number generation issues in Chapter 7, "Random Numbers." 

For a more theoretical discussion that also covers many practical issues in depth, please see Chapter 3, "Random Numbers,” 
in Donald E. Knuth’sT heArt of Computer Programming, Volume2 (Seminumerical Algorithms), 2nd ed.; Reading, 

M assachusetts: Addison-Wesley Publishing Company, 1981. 

C0NF0RMST0 

SVID 3, BSD 4.3, ISO 9899 

SEE ALSO 

random(3), srandom(3), initstate(3), setstate(3) 

GNU, 18 May 1995 


random, srandom, initstate,setstate 

random, srandom, initstate, setstate— Random number generator 
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SYNOPSIS 

#include <stdlib.h> 

long int random(void); 

void srandom(unsigned int seed); 

char *initstate(unsigned int seed, char *s t a t e,int n); 
char *setstate(char *state); 


DESCRIPTION 

The random)) function uses a nonlinear additive feedback random number generator employing a default table of size 31 long 
integers to return successive pseudo-random numbersin the range from 0 to randjiax. The period ofthisrandom number 
generator is very large, approximately 1 6* < ( 2 ** 31 )- 1 ). 

Thesrandomo function sets its argument as the seed foranew sequence of pseudo-random integers to be returned by 
random ((.These sequences are repeatable by calling srandomo with the same seed value. If no seed value is provided, the 
random) > function is automatically seeded with a value of 1 . 

Theinitstate)) function allows a state array st ate to beinitialized for use by random)). The size of the state array n isused by 
initstate)) to decide how sophisticated a random number generator it should use—the larger the state array, the better the 
random numbers will be. seed istheseed for the initialization, which specifies a starting point for the random number 
sequence, and provides for restarting at the same point. 

Thesetstate)) function changes the state array used by the random)) function. The state array state isused for random 
number generation until the next call to initstate 0 or setstate)). state must first have been initialized using initstate)). 

RETURN VALUE 

The random)) function returns a value between 0 and rand_max. Thesrandom)) function returns no value.The initstate)) 
and setstate)) functions return a pointer to the previous state array. 

ERRORS 

einval A state array of less than 8 bytes was specified to initstate)). 

NOTES 

Current "optimal" values for the size of the state array n ares, 32, 64 ,128, and 256 bytes; other amounts will be rounded 
down to the nearest known amount. Using less than 8 bytes will cause an error. 

C0NF0RMST0 

BSD 4.3 


SEE ALSO 

rand(3), srand(3) 


GNU, 28 March 1993 


readdir 

readdir— Reads a directory 

SYNOPSIS 


#include <sys/types.h> 

#include <dirent.h> 

struct dirent *readdir(DIR *dir); 



readv, writs/ 



DESCRIPTION 

T he readdiri ) function returns a pointer to a dirent structure representing the next directory entry in the di rectory stream 
pointed to by di r . It returns null on reaching the end-of-file or if an error occurred. 

The data returned byreaddiro isoverwritten by subsequent calls to readdiro for the same directory stream. 

According to PO SIX, thedirent structure containsa field char d namen of unspecified size, with at most name_max characters 
preceding the terminating null character. Use of other fields will harm the portability of your programs. 

RETURN VALUE 

The readdiro function returns a pointer to a dirent structure, or null if an error occursor end-of-file is reached. 

ERRORS 

ebadf Invalid di rectory stream descriptor dir 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3 

SEE ALSO 

read(2), opendir(3), closedir(3), rewinddir(3), seekdir(3), telldir(3), scandir(3) 

22 April 1996 


readv, writev 

readv, writev— Reads or writes data into multiple buffers 

SYNOPSIS 

#include <sys/uio.h> 

int readv(int filedes, const struct iovec *vector, 
size_t count ) ; 

int writev(int filedes, const struct iovec *vector, 
size_t count ); 

DESCRIPTION 

T he readv o function reads count blocks from the file associated with the fi le descri ptor f i i edes into the multiple buffers 
described by vector. 

The writev o function writes at most count blocks descri bed by vector to the file associated with the file descri ptor f i i edes. 

The pointer vector points to a struct iovec defined in <sys/uio. h> as 

struct iovect 
{ 

void *iovbase; /* Starting address */ 
size_t iov_len; /* Number of bytes */ 

} ; 

Buffers are processed in the order vector [ 0 ], vector [ i ], ... vector [count]. 

T he readv o function works just like read(2) except that multiple buffers are filled. 

Thewritevo function worksjust likewrite(2) except that multiple buffers are written out. 

RETURN VALUES 

The readv o function returnsthe number of bytes or-i on error; thewritevo function returnsthe number of bytes written. 
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ERRORS 

The readv() and writevo functions can fail and set err no to the following values: 
ebadf td is not a valid file descriptor. 

einval td is unsuitable for reading (for readvo) or writing (for writevo). 

efault but is outside the processes' addressspace. 

eagain N onblocking I/O had been selected in the openo call, and reading or writing could not be 

done immediately. 

eintr Reading or writing was interrupted before any data was transferred. 

C0NF0RMST0 

unknown 

BUGS 

It is not advisable to mix cal Is to functions like readvo or writevo, which operate on file descriptors, with the functions 
from thestdio library; the results will be undefined and probably not what you want. 

SEE ALSO 

read(2), write(2) 

GNU ,25 April 1993 


realpath 

reaipath — Returns thecanonicalized absolute pathname 

SYNOPSIS 

#include <sys/param.h> 

#include <unistd.h> 

char *realpath(char *path, char resol v e d _ p a t h []) ; 


DESCRIPTION 

reaipath expands all symbolic links and resolves references to / ./,/../ and extra / characters in the null-terminated string 
named by path and stores thecanonicalized absolute pathname in the buffer of sizeMAXPATHLEN named by resoived_path. The 
resulting path will have no symbolic link, /. /, or /.. / components. 


RETURN VALUE 

If there is no error, it returns a pointer to the resoived_path. 

Otherwise, it returns a null pointer and places in resoived_path the absolute pathname of the path component that could not 
be resolved. The global vari able e r r no i s set to indicate the error. 


ERRORS 

ENOTDIR 

EINVAL 

ENAMETOOLONG 

ENOENT 

EACCES 

ELOOP 

EIO 


A component of the path prefix is not a directory. 

T he pathname contains a character with the high-order bit set. 

A component of a pathname exceeded maxnamlen characters, or an entire path 
name exceeded maxpathlen characters. 

T he named file does not exist. 

Search permission is denied for a component of the path prefix. 

T oo many symbolic links were encountered in translating the pathname. 

An I/O error occurred whilereadingfrom thefilesystem. 



regcomp, regexeregerror, regfree 


SEE ALSO 

readlink(2), getcwd(3) 



GNU, 29July 1994 


Re_comp,re_exec 

re_comp, re_exec — BSD regex functions 

SYNOPSIS 

#include <regex.h> 

char *re comp(char *regex); 

int re exec(char *string); 


DESCRIPTION 

ne_comp is used to compile the null-terminated regular expression pointed to by regex. The compiled pattern occupies a static 
area, the pattern buffer, which is overwritten by subsequent use of re_comp. If regex is null, no operation is performed and 
the pattern buffer's contents are not altered. 

re_exec is used to assess whether the null-terminated string pointed to by string matches the previously compiled regex. 

RETURN VALUE 

re_comp returns null on successful compilation of regex; otherwise, it returns a pointer to an appropriate error message. 
re_exec returns i for a successful match, zero for failure. 

C0NF0RMST0 

BSD 4.3 


SEE ALSO 

regex(7), GNU regex manual 


Linux , 14 July 1995 


regcomp,regexec,regerror,regfree 

regcomp, regexec, regerror, regfree — POSIX regex functions 

SYNOPSIS 

#include <regex.h> 

int regcomp(regex_t *preg, const char *regex,int cflags); 

int regexec(const regexjt *pr eg, const char *string, size_t nmatch, regmatch_t pmat ch[], int eflags); 
size_t regerror(int errcode, const regex_t *preg, char *errbuf, size_t errbufsize); 
void regfree(regexjt *preg); 

POSIX REGEX COMPILING 

regcomp is used to compile a regular expression into a form that is suitable for subsequent regexec searches. 

regcomp is supplied with preg, a pointer to a pattern buffer storage area; regex, a pointer to the null-terminated string; and 
cf i ags.fi ags used to determine the type of compilation. All regular expression searching must be done via a compiled pattern 
buffer; thus, regexec must always be supplied with the address of a regcomp initialized pattern buffer. 
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cf i ags may be the bitwise or of one or more of the following: 


REG_EXTENDED 

REG_ICASE 

REG_NOSUB 


REGNEWLINE 


UsePOSIX extended regular expression syntax when interpreting regex. If 
not set, PO SIX basic regular expression syntax is used. 

Do not differentiate case. Subsequent regexec searches using this pattern 
buffer will be case-in sen si five. 

Support for substring addressing of matches is not required. Then mate ti and 
p ma t c h parameters to regexec areignored ifthe pattern buffer supplied was 
compiled with thisflagset. 

M atch-any-character operators don't match a newline. A nonmatching list 
([-...]) notcontaininganewlinematchesanewline. M atch-beginning-of- 
line operator (-) matches the empty string immediately after a newline, 
regardless of whether ef i ags, the execution flags of regexec, contains 
reg_notbol. M atch-end-of-1 ine operator ($) matches the empty string 
immediately before a newline, regardless of whether ef i ags contains 

REG NOTEOL. 


POSIX REGEX MATCHING 


regexec is used to match a null-terminated string against the precompiled pattern buffer, pr eg. nmatch and p mate h are used to 
provide information regarding the location of any matches, ef i ags may be the bitwise or of one or both of reg_notbol and 
reg_noteol, which cause changes i n matching behavior described in thefollowing list. 

reg_notbol T he match-begi nning-of-li ne operator always fai Is to match (but seethe 

compilation flag regnewline, in the precedi ng subsection). Thisflag may beused 
when different portions of a string are passed to regexec and the beginning of the 
string should not be i nterpreted as the begi nni ng of the li ne. 
reg_noteol T he match-end-of-l ine operator always fai Is to match (but see the compilation 

flag reg_newline, in the precedi ng subsection). 


BYTE OFFSETS 

Unless reg_nosub was set for the compilation of the pattern buffer, it is possible to obtain substring match addressing 
information, pmatch must be dimensioned to have at least nmatch elements. These are filled in by regexec with substring 
match addresses. Any unused structure elements will contain the value - i. 

T he regmatch_t structure that isthetype of pmatch is defined in regex. h: 

typedef struct 
{ 

regoff_t rm_so; 
regoff_t rm_eo; 

} regmatch_t; 


Each rm_so element that is not -i indicates the start offset of the next largest substring match within the string. The relative 
rm_eo element indicates the end offset of the match. 

POSIX ERROR REPORTING 

regerror is used to turn the error codes that can be returned by both regcomp and regexec into error message strings. 

regerror is passed the error code, e r r c ode ; the pattern buffer, pr eg ; a pointer to a character string buffer, er r but ; and the size 
of the string buffer, errbuf_si ze. It returns the size of the e r r buf required to contain the null-terminated error message string. 
If both er r buf and e r r buf _s i z e are non-zero, er r buf isfilled in with thefirst errbuf_size - i characters of the error message 
and a terminating null. 



remove 



POSIX PATTERN BUFFER FREEING 

Supplying regfree with a precompiled pattern buffer, pr eg will free the memory allocated to the pattern buffer by the 
Compiling process, regcomp. 

RETURN VALUE 

regcomp returns zero for a successful compilation or an error code for failure, 
regexec returns zero for a successful match or reg_nomatch for failure 


ERRORS 


Thefollowing errors can be returned by regcomp: 


REG_BADRPT 

REG_BADBR 

REG_EBRACE 

REG_EBRACK 

REG_ERANGE 

REG_ECTYPE 

REG_EPAREN 

REG_ESUBREG 

REG_EEND 

REG_ESCAPE 

REG_BADPAT 

REG_ESIZE 

REG_ESPACE 


Invalid useof repetition operators, such asusing* as the first character 
Invalid useof back reference operator 
U nmatched brace interval operators 
Unmatched bracket list operators 

Invalid useof the range operator; for example, the ending point of the range 

occurs prior to thestarting point 

U nknown character class name 

Unmatched parenthesis group operators 

Invalid back reference to a subexpression 

N on-specific error 

Invalid escape sequence 

Invalid useof pattern operators such as group or list 

Compiled regular expression requires a pattern buffer larger than 64Kb 

The regex routines ran out of memory 


C0NF0RMST0 

POSIX 

SEE ALSO 

regex(7), GNU regex manual 


Linux , 13 July 1994 


remove 

remove— Deletes a name and possibly the file to which it refers 

SYNOPSIS 

#include <stdio.h> 

int remove(const char *pathname); 

DESCRIPTION 

remove deletes a name from thefilesystem. If that name was the last link to a file and no processes have the file open, the file 
is deleted and the space it was using is made available for reuse. 

If the name was the last link to a file but any processes still have the file open, the file will remain in existence until the last 
file descriptor referring to it is closed. 
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If the name referred to a symbolic link, the link is removed. 

If the name referred to a socket, fifo, or device, the name for it is removed, but processes that have the object open may 
continue to use it. 

RETURN VALUE 

On success, zero is returned. On error, -i is returned, and errno is set appropriately. 


ERRORS 

EFAULT 

pat h n a me poi nts outsi de your accessi bl e address space. 


EACCES 

W rite access to the directory containing pathname isnot allowed for the 
process's effective uid, or one of the directories in pathname did not allow search 
(execute) permission. 


EPERM 

The directory containing pathname has thesti cky-bit (s_isvtx) set and the 
process's effective uid is neither the uid of the file to be deleted nor that of the 
directory containing it. 


ENAMETOOLONG 

pat h n a me WastOO long. 


ENOENT 

A directory component in pat hname does not exist or isa dangling symbolic 
link. 


ENOTDIR 

A component used as a directory in pathname isnot, in fact, a directory. 


EISDIR 

pathname refers to a directory. 


ENOMEM 

Insufficient kernel memory was available. 

EROFS 


pathname refers to a fi le on a read-only filesystem. 

C0NF0RMST0 



SVID, AT&T, POSIX, X/OPEN , BSD 4.3 

BUGS 

Inadequacies in the protocol underlying N FS can cause the unexpected disappearance of files that are still being used. 

SEE ALSO 

unlink(2), rename(2), open(2), rmdir(2), mknod(2), mkfifo(3), link(2), rm(l), unlinkf8) 

Linux , 13 July 1994 

res_query, res_search, res_mkquery, res_send, res_init, 
dn_comp, dn_expand 

res_query, res_search, nes_mkquery, res_send, res_init, dn_comp, dn_expand —Resolver routines 

SYNOPSIS 

#include <sys/types.h> 

#include <netinet/in.h> 

#include <arpa/nameser.h> 

#include <resolv.h> 

res_query(dname, class, type, answer, anslen) 

const char *d n a me; 

int class, type; 

u_char *answer ; 

int anslen; 



res_query, res_search, res_mkquery, res_send, res_init, dn_comp, dn_expand 



res_search(dname, class, type, answer, anslen) 
const char *d n a me; 
int class, type; 
u char *a ns we r ; 
int anslen; 

res mkquery(op, d n a me, class, type, data, datalen, newrr, buf, buflen) 
int op; 

const char *d n a me; 
int class, type; 
const char *data; 
int dat a I en; 
struct rrec *newr r ; 
u_char *buf ; 
int buflen; 

res_send(msg, ms glen, answer, anslen) 

const u_char *msg; 

int msgl en; 

u_char *answer ; 

int anslen; 

res_init() 

dn_comp(exp_dn, comp_dn, length, dnptrs, lastdnptr) 
const char *exp_dn; 
u char *comp_dn; 
int length; 

u_char **dnptrs, **l astdnptr ; 

dn_expand(msg, eomorig, comp_dn, exp_dn, length) 

const u_char *msg, *eomor i g, *comp_dn; 

char *e x p_ d n; 

int length; 

hstrerror(int err); 

DESCRIPTION 

These routines are used for making, sending and interpreting query and reply messages with Internet domain name servers. 

Global configuration and state information that is used by the resolver routines is kept in thestructure_res. M ost of the 
values have reasonable defaults and can be ignored. Options stored in _res. options are defined in resoiv.h and areas 
follows. Options are stored as a simple bit mask containing the bitwise or of the options enabled. 


RES_INIT 

T rue if the initial name server address and default domain name are 
initialized (that is, res_init has been called). 

RES_DEBUG 

Print debugging messages. 

RES_AAONLY 

Accept authoritative answers only. W ith this option, res_send should 
continue until itfindsan authoritative answer or finds an error. 

C urrently, this is not implemented. 

RESJJSEVC 

UseTCP connections for queries instead of UDP datagrams 

RES_STAYOPEN 

U sed with resjjsevc to keep theTC P connection open between queries. 
This is useful only in programs that regularly do many queries. UDP 
should be the normal mode used. 

RES_IGNTC 

Unused currently (ignore truncation errors—don't retry with TCP). 

RES_RECURSE 

Set the recursion-desired bit in queries. This isthe default. (res_send does 
not do iterative queries and expects the name server to handle recursion.) 
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RESDEFNAMES 


RES_DNSRCH 


RESNOALIASES 


If set, nes_search will append the default domain name to single¬ 
component names (those that do not contain a dot). Thisoption is 
enabled by default. 

If thisoption is set, res_search will search for hostnames in the current 
domain and in parent domains; see hostname(7). This is used by the 
standard host lookup routinegethostbyname(3).Thisoption isenabled 
by default. 

Thisoption turns off the user level aliasing feature controlled by the 
hostaliases environment variable. N etwork daemons should set this 
option. 


T he res_init routine reads the configuration file (if any; seeresoiver(5)) to get the default domain name, search list and the 
Internet address of the local n am e server! s). If no server is configured, the host running the resolver is tried. T he current 
domain nameisdefined by the hostname if not specified in theconfiguration file; it can be overridden by the environment 
variable localdomain. This environment variable may contain several blank-separated tokens if you wish to override the 
search list on a per-process basis. This is similar to the search command in theconfiguration file Another environment 
variable (res_options) can beset to override certain internal resolver options that are otherwise set by changing fields in the 
res structure or are inherited from theconfiguration file's options command. The syntax of the res_options environment 
variable is explained in resoiver(5). Initialization normally occurs on the first call to one of the other resolver routines. 

T he res_query function provides an interface to the server query mechanism. It constructs a query, sends it to the local 
server, awaits a response, and makes preliminary checks on the reply. The query requests information of the specified type 
and class for the specified fully-qualified domain named name. The reply message is left in the answer buffer with length 
ansi en supplied by thecaller. 

T he res_search routi ne makes a query and awaits a response like resjuery, but in addition, it implements the default and 
search rules controlled by the res_defnames and res_dnsrch options. 1 1 returns the first successful reply. 

The remaining routines are lower-level routines used by res_query. The resjnkquery function constructs a standard query 
message and places it in but. It returns the size of the query, or -i if the query is larger than bufien. The query type op is 
usually query, but can beany of the query types defined in <arpa/nameser.h>. The domain name for the query is given by 
dname. Newrr is currently unused but isintended for making update messages. 

T he res_send routine sends a preformatted query and returns an answer. It will call res_init if res_init is not set, send the 
query to the local name server, and handle time-outs and retries. The length of the reply message is returned, or-i if there 
were errors. 

T he dn_comp function compresses the domain nameexpjin and stores it in compjin.T he size of the compressed name is 
returned or -i if there were errors. The size of the array pointed to by comp_dn is given by length. The compression uses an 
array of pointers dnptrs to previously-compressed names in the current message. The first pointer pointsto the beginning of 
the message and the list ends with null. The limit to the array is specified by lastdnptr. A side effect of dn_comp is to update 
the list of pointers for labels inserted into the message as the name is compressed. If dnptr is null, names are not compressed. 
If lastdnptr isNULL, the list of labels is not updated. 

T he dn_expand entry expands the compressed domain narnecomp_dn to a full domain name. The compressed name is 
contained in a query or reply message; msg is a pointer to the beginning of the message. The uncompressed name is placed in 
the buffer indicated by exp_dn, which is of size length. The size of compressed name is returned or -i if there was an error. 


FILES 


/etc/resolv.conf 


See resolver(5) 



SEE ALSO 

gethostbyname(3), named(8), resolven(5), hostname(7), 

RFC 1032, RFC 1033, RFC1034, RFC1035, RFC974 
SM M : 11 N ame Server 0 perations Guide for BIND 


rint 
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rewinddir 

rewinddir— Resets directory stream 

SYNOPSIS 

#include <sys/types.h> 

#include <dirent.h> 
void rewinddir(DIR *dir); 

DESCRIPTION 

The rewinddiro function resets the position of the directory stream dir to the beginning of the directory. 

RETURN VALUE 

Thereaddiro function returns no value. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3 

SEE ALSO 

opendir(3), readdir(3), closedir(3), seekdir(3), telldir(3), scandir(3) 

11Junel995 


rint 

rint— Rounds to closest integer 

SYNOPSIS 

#include <math.h> 
double rint(double x); 

DESCRIPTION 

The rinto function rounds* to an integer value according to the prevalent rounding mode. The default rounding mode is 
to round to the nearest integer. 

RETURN VALUE 

The rinto function returns theinteger value as a floating-point number. 

CON FORMS TO 


BSD 4.3 
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SEE ALSO 

abs(3), ceil(3), fabs(3), floor(3), labs(3) 


6 Junel993 


rquota 

rquota — I mplements quotas on remote machines 

SYNOPSIS 

/usr/include/rpcsvc/rquota.x 

DESCRIPTION 

The rquota/ ) protocol inquires about quotas on remote machines. It is used in conjunction with NFS because NFS itself 
does not implement quotas. 

PROGRAMMING 

#include <rpcsvc/rquota.h> 

The following XD R routines are available in librpcsvc: xdr_getquota_arg: 

xdr_getquota_rslt 

xdr_rquota 


SEE ALSO 

quota(l), quotactl(2) 


6 October 1987 


scandir,alphasort 

scandir, alphasort— Scan a di rectory for matchi ng entries 

SYNOPSIS 

#include <dirent.h> 

int scandir(const char *di r , struct dirent ***namelist, 
int (*sel ect )(const struct dirent *), 

int (*compar )(const struct dirent **, const struct dirent **)); 
int alphasort(const struct dirent **a, const struct dirent **b); 

DESCRIPTION 

The scandiro function scans the di rectory di r , calling select!) on each directory entry. Entries for which select!) returns 
non-zero are stored in strings allocated viamaiioco, sorted using qsorto with thecomparison function comparo, and 
collected in array n a me i i st that isaliocated viamaiioco. If select is null, all entries are selected. 

The alphasort!) function can beused as the comparison function for the scandiro function to sort the directory entries i nto 
alphabetical order. Its parameters are the two directory entries, aandb, to compare. 

RETURN VALUE 

The scandiro function returnsthe number of directory entries selected or -i if an error occurs. 

The aiphasorto function returns an integer less than, equal to, or greater than zero if the first argument is considered to be 
respectively less than, equal to, or greater than the second. 



scanf, fxanf, szanf, vsoanf, vsxanf, vfscanf 
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ERRORS 

enomem Insufficient memory to complete the operation 

C0NF0RMST0 

BSD 4.3 

EXAMPLE 

/* print files in current directory in reverse order */ 

#include <dirent.h> 
main(){ 

struct dirent * *n a me I i st ; 
int n; 

n = scandir(".", &n a me I i s t , 0, al phasort ); 
if (n < 0) 

perror("scandir"); 

else 

while(n—) printf("%s\n", namel i st [n]->d_name); 

} 


SEE ALSO 

opendir(3), readdir(3), closedir(3), rewinddir(3), telldir(3), seekdir(3) 


GNU, 11 April 1996 


scant, f scant, sscanf, vscanf, vsscanf, vfscanf 

scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf — Input format conversion 

SYNOPSIS 

#include <stdio.h> 

int scanf( const char *format, ...); 

int fscanf( FILE *stream, const char *format, ...); 

int sscanf( const char *str, const char *format, ...); 

#include <stdarg.h> 

int vscanf( const char *for mat ,valist ap); 

int vsscanf( const char *str, const char *for mat ,va_ist ap); 

int vfscanf( FILE *s t ream, const char *for mat ,va_list ap); 

DESCRIPTION 

The scanf family of functions scans input according to a format as described below. This format may contain conversion 
specifiers; the results from such conversions, if any, are stored through the pointer arguments The scant function reads 
input from the standard input stream stdin, fscanf reads input from the stream pointer stream, and sscanf reads its input 
from the character string pointed to by st r. 

The vfscanf function isanalogousto vfprtntf (3) and readsinput from thestream pointer stream using a variable argument 
list of pointers (see stdarg(3)). The vscanf function scans a variable argument list from the standard input and the vsscanf 
function scansitfrom a string; these are analogous to thevprintf and vsprintf functions respectively. 

Each successive pointer argument must correspond properly with each successive conversion specifier. All conversions are 
introduced by the % (percent sign) character. The format string may also contain other characters. Whitespace (such as 
blanks, tabs, or newlines) in the format string match any amount of whitespace including none, in the input. Everything else 
matches only itself. Scanning stops when an input character does not match such a format character. Scanning also stops 
when an input conversion cannot be made. 
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CONVERSIONS 

Following the % character introducing a conversion, there may be a number of flag characters, as follows: 

* Suppresses assignment. The conversion that follows occurs as usual, but no pointer is used; the result of 
the conversion is simply discarded. 

a Indicates that the conversion will bes, maiioc will be applied to the needed memory space for the string, 
and the pointer to it will be assigned to the char pointer variable, which does not have to be initialized 
before. T hisflag does not exist in AN SI C. 

h Indicates that the conversion will be one of dioux or n and the next pointer is a pointer to a short int 
(rather than int). 

1 Indicates either that the conversion will be one of dioux or n and the next pointer is a pointer to a long 
int (rather than int), or that the conversion will be one of etg and the next pointer is a pointer to 
double (rather than float). Specifying two 1 flags is equivalent to the l flag. 
l Indicates that the conversion will be either ef g and the next pointer is a pointer to long double or the 
conversion will bedioux and the next pointer isa pointer to long long. (Note that long long isnotan 
ANSI C type. Any program using thiswill not be portable to all architectures), 
q Equivalent to l.T hisflag does not exist in ANSI C. 

In addition to these flags, there may bean optional maximum field width, expressed asa decimal integer, between the% and 
the conversion. If no width is given, a default of inf inity is used (with one exception, below); otherwise, at most this many 
characters are scanned in processing the conversion. Before conversion begins, most conversions skip whitespace; this 
whitespace is not counted against thefield width. 

The following conversions are available: 

% M atchesa literal %. That is, %% in the format string matches a single input % character. N o conversion is 

done, and assignment does not occur. 

d M atchesan optionally signed decimal integer; the next pointer must be a pointer to int. 

d Equivalent to id; this exists only for backwards compatibility. 

i M atches an optionally signed integer; the next pointer must be a pointer to int. T he integer is read in 

base 16 if it begins with ox or ox, in base 8 if it begins with o, and in base 10 otherwise. 0 nly 
characters that correspond to the base are used. 

o M atchesan unsigned octal integer; the next pointer must be a pointer to unsigned int. 

u M atchesan unsigned decimal integer; the next pointer must be a pointer to unsigned int. 

x M atchesan unsigned hexadecimal integer; the next pointer must be a pointer to unsigned int. 

x Equivalent to x. 

f M atchesan optionally signed floating-point number; the next pointer must be a pointer to float, 

e Equivalent to f. 

g Equivalent to f. 

e Equivalent to f. 

s M atches a sequence of nonwhitespace characters; the next pointer must be a pointer to char, and the 

array must be large enough to accept all the sequence and the terminating N U L character. The input 
string stops at whitespace or at the maxi mum field width, whichever occurs first, 
c M atches a sequence of width count characters (default 1); the next pointer must be a pointer to char, 

and there must be enough room for all the characters (no terminatingNUL is added). The usual skip of 
leading whitespace is suppressed. T o skip whitespace first, use an explicit space in theformat. 

I M atchesa nonempty sequence of characters from the specified set of accepted characters; the next 

pointer must be a pointer to char, and there must be enough room for all the characters in the string, 
plus a terminating nul character. The usual skip of leading whitespace is suppressed. The string is to be 
made up of characters in (or not in) a particular set; the set is defined by the characters between the 
open bracket [ character and a close bracket ] character. The set excludes those characters if the first 



seekdir 



character after the open bracket isa circumflex (-). T o include a close bracket in the set, make it the 
first character after the open bracket or the circumflex; any other position will end the set. The hyphen 
character (-) is also special; when placed between two other characters, it adds all intervening 
characters to the set. T o include a hyphen, make it the last character before the final close bracket. For 
instance, ["] 0-9- ] meansthe set "everything except close bracket, zero through nine, and hyphen." 
The string ends with the appearance of a character not in (or, with a circumflex, in) the set or when 
the field width runs out. 

p M atchesa pointer value (as printed by %p in printf (3); the next pointer must be a pointer to void, 

n N othing is expected; instead, the number of characters consumed thusfar from the input is stored 

through the next pointer, which must be a pointer to int. This is not a conversion, although it can be 
suppressed with the* flag. 

RETURN VALUES 

These functions return the number of input items assigned, which can be fewer than provided for, or a/en zero, in the event 
of a matching failure. Zero indicates that, while there was input available, no conversions were assigned; typically, this is due 
to an invalid input character, such as an alphabetic character for a %d conversion. The value eof is returned if an input failure 
occurs before any conversion such as an end-of-file occurs. If an error or end-of-file occurs after conversion has begun, the 
number of conversions which were successfully completed is returned. 

SEE ALSO 

strtol(3), strtoul(3), strtod(3), getc(3), printf(3) 

STANDARDS 

The functions f scant, scant, and sscant conform to AN SI C 3.159-1989 (AN SI C). 

T he q flag is the BSD 4.4 notation for long long, whilen or theusageofL in integer conversions isthe GNU notation. 

The Linux version of these functions is based on theGN U libio library. T akea look at the into documentation of GN U 
nbc (glibc-1.08) for a more concise description. 

BUGS 

All functions are fully AN SI C3.159-1989-conformant, but provide the additional flags q and a as well as an additional 
behavior of the l and 1 flags. The latter may be considered to be a bug, as it changes the behavior of flags defined in AN SI 
C 3.159-1989. 

Some combinations of flags defined by AN SI C are not making sense in ANSI C (for example %Ld). While they may have a 
well-defined behavior on Linux, this need not to be so on other architectures. Therefore, it usually is better to use flags that 
are not defined by AN SI C at all, that is, useq instead of l in combination with diouxx conversionsor 11. 

T he usage of q is not the same as on BSD 4.4, as it may be used in float conversions equivalently to l. 

Linux man page 1 N ovember 1995 


seekdir 

seekdir— Sets the position of the next readdiro call in the directory stream. 

SYNOPSIS 

#include <dirent.h> 

void seekdir(DIR *di r ,off_t offset ); 

DESCRIPTION 

Theseekdiro function sets the location in the directory stream from which thenext readdiro call will start, seekdiro 
should beused with an offset returned by teiidiro. 
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RETURN VALUE 

Theseekdiro function returns no value. 

C0NF0RMST0 

BSD 4.3 

SEE ALSO 

lseek(2), opendir(3), readdir(3), closedir(3), rewinddir(3), telldir(3), scandir(3) 


31 March 1993 


setbuf, setbuffer, setlinebuf,setvbuf 

setbuf, setbuffer, setlinebuf, setvbuf —Stream buffering operations 

SYNOPSIS 

#include <stdio.h> 

int setbuf( FILE *stream, char *buf); 

int setbuffer( FILE *st r eam, char *buf , size_t si ze); 

int setlinebuf( FILE *s t ream); 

int setvbuf( FILE *s t ream, char *buf, intmode , size_t size); 

DESCRIPTION 

The three types of buffering available are unbuffered, block buffered, and line buffered. When an output stream is unbuf¬ 
fered, information appearson the destination file or terminal as soon as written; when itisblock buffered, many characters 
are saved up and written as a block; when it is line buffered, characters are saved up until a newline is output or input is read 
from any stream attached to a terminal device (typically stdin). Thefunction tfiush(3) may be used to force the block out 
early. (See tciose(3).) N ormally all files are block buffered. W hen the first I/O operation occurs on a file maiioc(3) is called, 
and a buffer is obtained. If a stream refers to a terminal (asstdout normally does), it is line buffered. The standard error 
stream stderr is always unbuffered. 

The setvbuf function may be used at any time on any open stream to change its buffer. The mode parameter must be one of 
thefollowing three macros: 


IONBF 

Unbuffered 

IOLBF 

Line buffered 

IOFBF 

F ul ly buffered 


Except for unbuffered files, thebuf argument should point to a buffer at least size bytes long; this buffer will be used instead 
of the current buffer. If the argument but is null, only the mode is affected; a new buffer will be allocated on the next read or 
write operation. The setvbuf function may be used at anytime, but can only change the mode of a stream when it is not 
"active"; that is before any I/O, or immediately after a call to ffiush. 

The other three calls are, in effect, simply aliases for calls to setvbuf. The setbuf function is exactly equivalent to the call: 

setvbuf(st ream, but, buf ?_IOFBF :_IONBF, BUFSIZ); 

The setbuffer function is the same, except that the size of the buffer is up to the caller, rather than being determined by the 
default bufsiz. The setlinebuf function is exactly equivalent to the call: 

setvbuf(strearn, (char *)NULL,_IOLBF, 0); 
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SEE ALSO 

fopen(3), fclose(3), fread(3), malloc(3), puts(3), pnintf(3) 

STANDARDS 

T he setbuf and setvbuf functions conform to AN SI C 3.159-1989 (AN SI C). 

BUGS 

The setbuf fen and setiinebuf functions are not portable to versions of BSD before 4.2BSD, and may not be available under 
Linux. On 4.2BSD and 4.3BSD systems setbuf always uses a suboptimal buffer size and should be avoided. You must make 
sure that both buf and thespace it points to still exist by the time stream is closed, which also happens at program termina¬ 
tion. For example, thefollowing is Illegal: 

#include <stdio.h> 
int main() 

{ 

char buf[BUFSIZ]; 
setbuf(stdin, buf ); 
printf("Hello, world!\n"); 
return 0; 

} 

BSD man page, 29 N ovember 1993 

setenv 

setenv— Changes or adds an environment variable 

SYNOPSIS 

#include <stdlib.h> 

int setenv(const char *name, const char *value,int overwrite); 
void unsetenv(const char *name); 

DESCRIPTION 

T he setenv( ) function adds the variable name to the environment with the value value, if name does not already exist. If name 
does exist in the environment, then its value is changed to value if overwrite is non-zero; if overwrite is zero, then the value 
of name isnot changed. 

Theunsetenvo function deletes the variable name from the environment. 

RETURN VALUE 

T he setenv( > function returnszero on success, or -i if there was i nsufficient spacein the environment. 

C0NF0RMST0 

BSD 4.3 

SEE ALSO 

getenv(3), putenv(3) 


BSD, 4 April 1993 



Part III: Library Functions 



setjmp 

set jmp— Saves stack context for nonlocal goto 

SYNOPSIS 

#include <setjmp.h> 
int setjmp(jnp_buf env ); 

DESCRIPTION 

setjmp and long j mp( 3) are useful for dealing with errors and interrupts encountered in a low-level subroutine of a program, 
setjmp () saves the stack context/environment in env for later use by long jmp(). The stack context will be invalidated if the 
function which called setjmpo returns. 

RETURN VALUE 

It returns the value 0 if returning directly and non-zero when returning from longjmpo using the saved context. 

C0NF0RMST0 

POSIX 

NOTES 

POSIX does not specify if the signal context will be saved or not. If you want to save signal masks, usesigsetjmp(3). setjmpo 
makes programs hard to understand and maintain. If possible, an alternative should be used. 

SEE ALSO 

longjmp(3), sigsetjmp(2), siglongjmp(2) 

25 November 1994 


setlocale 

setiocaie — Sets the current locale 

SYNOPSIS 

#include <locale.h> 

char *setlocale(int category, const char * locale); 


DESCRIPTION 

The setiocaie) ) function isused to set or query the program's current locale. Ifi ocai e isC or POSIX, thecurrent locale is 
set to the portable locale. 

If i oca i e is 11,1 , the locale is set to the default locale that is selected from the environment variable lang. 


On startup of the main program, the portable locale is selected as default. 
Theargumentcategory determines which functions are influenced by the new locale: 


LC_ALL 

LC_COLLATE 

LC_CTYPE 

LC_MONETARY 

LC_NUMERIC 

LC_TIME 


For all of the locale. 

Forthefunctionsstrcoiio and strxfrmo. 

For the character classification and conversion routines. 

For localeconv)). 

For the decimal character. 

For strttime)). null if the request can not be honored. This string may be 
allocated in static storage. 



s/gemptyst, gcfillset, sigadd^t, sigdelset, sigismember 



A program may be made portable to all locales by calling setiocaie(LC_ALL, .) after program initialization, by using the 

values returned from aiocaieoonv() call for locale-dependent information and by using strcoiio or strxfrmo to compare 
strings. 

C0NF0RMST0 

ansi c, POSIX.1 

Linux supports the portable locales C and POSIX and also the European Latin-1 and Russian locales. 

The printf () family of functions may or may not honor the current locale. 

SEE ALSO 

locale(l), localedef(l), strcoll(3), isalpha(3), localeconv(3), strftime(3), locale(7) 

GNU, 18 April 1993 


siginterrupt 

siginterrupt— Allowssignalsto interrupt system calls 

SYNOPSIS 

#include <signal.h> 

int siginterrupt(int sig,int flag); 


DESCRIPTION 

The siginterrupt( ) function changes the restart behavior when asystem call is interrupted by the signal sig.lf the flag 
argument is false ( 0 ), then systems cal Is will be restarted if interrupted by the specified signal sig. This is the default behavior 
in Linux. H owever, when anew signal handler is specified with thesignai(2) function, the system call is interrupted by 
default. 

If the flag argument is true ( 1 ) and no data has been transferred, then a system call interrupted by the signal sig will return 
-1 and the global variableermo will be set to eintr. 

If the flag argument is true ( 1 ) and data transfer has started, then the system call will be interrupted and will return the 
actual amount of data transferred. 

RETURN VALUE 

The siginterrupt! ) function returnso on success, or -1 if the signal number sig isinvalid. 

ERRORS 

einval T he specified signal number isinvalid. 


conforms™ 

BSD 4.3 

SEE ALSO 

signal(2) 


13 April 1993 


sigemptyset, sigfillset, sigaddset,sigdelset,sigismember 

sigemptyset, sigfillset, sigaddset, sigdelset, sigismember— PO SIX signal set operations 
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SYNOPSIS 

#include <signal.h> 

int sigemptyset(sigset_t *set); 

int sigfillset(sigset_t *set); 

int sigaddset(sigset_t *set ,int si gnum); 

int sigdeiset(sigset_t *s et ,int signum); 

int sigismemben(const sigset_t *set,int signum); 

DESCRIPTION 

T he sigsetops(3) functions allow the manipulation of POSIX signal sets. 

sigemptyset initializes the signal set given by set to empty, with all signals excluded from the set. 

sigfiiiset initializesset to full, including all signals. 

sigaddset and sigdeiset add and delete, respectively, signal signum from set. 

sigismember tests whether s i g nu m isa member of s et. 

RETURN VALUES 

sigemptyset, sigfuiiset, sigaddset, and sigdeiset return 0 on success and -i on error, 
sigismember returns i if signum isa member of set, 0 if signum is not a member, and -i on error. 

ERRORS 

einval si g isnot a valid signal. 


C0NF0RMST0 

POSIX 

SEE ALSO 

sigaction(2), sigpending(2), sigprocmask(2), sigsuspend(2) 


Linux 1.0, 24 September 1994 


sin 

sin— Sinefunction 

SYNOPSIS 

#include <math.h> 
double sin(double x); 

DESCRIPTION 

Thesino function returns thesineof x, wherex is given in radians. 

RETURN VALUE 

Thesino function returns a value between -i andi. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 
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sleep 


SEE ALSO 

acos(3), asin(3), atan(3), atan2(3), cos(3), tan(3) 


8Junel993 


sinh 

sinh— H yperbolic sine function 

SYNOPSIS 

#include <math.h> 
double sinh(double x); 

DESCRIPTION 

T he sinh o function returns the hyperbolic sine of x , which is defined mathematically as[exp(x)-exp(-x)] / 2. 

C0NF0RMST0 

SVID 3, PO SIX, BSD 4.3, ISO 9899 

SEE ALSO 

acosh(3), asinh(3), atanh(3), cosh(3), tanh(3) 

13Junel993 


sleep 

sleep— Sleeps for the specified number of seconds 

SYNOPSIS 

#include <unistd.h> 

unsigned int sleep(unsigned int seconds); 

DESCRIPTION 

sieepo makes the current process sleep until seconds seconds have elapsed or a signal arrives that is not ignored. 

RETURN VALUE 

The return value iszero if the requested time has elapsed, or the number of seconds left to sleep. 

C0NF0RMST0 

POSIX.1 

BUGS 

sieepo may be implemented using sigalrm; mixing calls to alarm o and sleep o is a bad idea. 

Using longjmp) ) from a signal handler or modifying the handling of sigalrm while sleeping will cause undefined results. 

SEE ALSO 

signal(2), alarm(2) 


GNU, 7April 1993 
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snprintf,vsnprintf 

snprintf, vsnprintf— Formatted output conversion 

SYNOPSIS 

#include <stdio.h> 

int snprintf ( char *str, size_t n, 
const char *f or mat , ... ); 

#include <stdarg.h> 

int vsnprintf ( char *str, size_t n, 
const char *format, va_list ap ); 

DESCRIPTION 

snprintf writes output to the string st r, under control of the f or mat string that specifies how subsequent arguments are 
converted for output. It is similar to sprintf(3), except that n specifies themaximum number of characters to produce. 

The trailing null character is counted towards this limit, so you should allocate at least n characters for the string s t r. 

vsnprintf is the equivalent of snprintf with the variable argument list specified directly as for vprintf. 

RETURN VALUE 

The return value is the number of characters stored, not including the terminating null. If this value equals n, then there was 
not enough space in st r for all the output. You should try again with a bigger output string. 

EXAMPLE 

H ere is a sample program that dynamically enlarges its output buffer: 

/* Construct a message describing the value of a 
variable whose name is NAME and whose value is 
VALUE. */ 
char * 

makejnessage (char *name, char *value) 

{ 

/* Guess we need no more than 100 chars of space. */ 
int size = 100; 

char *buffer = (char *) xmalloc (size); 
while (1) 

{ 

/* Try to print in the allocated space. */ 
int nchars = snprintf (buffer, size, 

"value of %s is %s", name, value); 

/* If that worked, return the string. */ 
if (nchars < size) 
return buffer; 

/* Else try again with twice as much space. */ 
size *= 2; 

buffer = (char *) xrealloc (size, buffer); 

} 

} 

C0NF0RMST0 

TheseareGNU extensions. 



stdarg 



SEE ALSO 

printf(3), sprintf(3), vsprintf(3), stdarg(3) 


GNU, 16 September 1995 


sqrt 

sqrt — Square root function 

SYNOPSIS 

#include <math.h> 
double sqrt(double x); 

DESCRIPTION 

The sqrt () function returns the non-negative square root of x. It fails and setsermo to edom, if x isnegative. 

ERRORS 

edom x isnegative. 

C0NF0RMST0 

SVID 3, PO SIX, BSD 4.3, ISO 9899 

SEE ALSO 

hypot(3) 

21Junel993 


stdarg 

stdarg— Variable argument lists 

SYNOPSIS 

#include <stdarg.h> 
void va_start( va_list ap, last); 
type va_arg( va_list ap, type); 
void va_end( va_list ap); 

DESCRIPTION 

A function may be called with a varying number of arguments of varying types. T he include file stdarg. h declares a type 
va_iist and defines three macros for stepping through a list of arguments whose number and types are not known to the 
called function. 

The called function must declare an object of type va_iist that is used by the macros va_start, va_arg, and va_end. 

T he va_start macro initializes a p for subsequent use by va_arg and va_end, and must be called first. 

The parameter last is the name of the last parameter before the variable argument list; that is, the last parameter of which 
the calling function knows the type. 

Because the address of this parameter is used in theva_start macro, it should not be declared as a register variable, a 
function, or an array type 

Theva start macro returns no value. 
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T he va_arg macro expands to an expression that has the type and value of the next argument in the call. T he parameter a p is 
the va_iist ap initialized by va_start. Each call to va_arg modifies a p so that the next call returns the next argument. The 
parameter type is a type name specified so that the type of a pointer to an object that has the specified type can be obtained 
simply by adding a * to type. 

If there is no next argument, or if type is not compatible with the type of the actual next argument (as promoted according 
to the default argument promotions), random errors will occur. 

T he first use of the va_arg macro after that of the va_start macro returns the argument after last. Successive invocations 
return the values of the remaining arguments 

T he va_end macro handles a normal return from the function whose variable argument list was initialized by va_start. 

T he va_end macro returns no value. 

EXAMPLE 

The function too takes a string of format characters and prints out the argument associated with each format character based 
on the type 

void foo(char *fmt, ...) 

{ 

va_list ap; 

int d; 

char c, *p, *s; 

va_start(ap, fmt); 

while (*fmt) 

switch(*fmt++) { 

case 's': /* string */ 

s = va_arg(ap, char *); 
printf("string %s\n", s); 
break; 

case 1 d 1 : /* int *1 

d = va_arg(ap, int); 
printf("int %d\n", d); 
break; 

case 'c': /* char */ 

c = va_arg(ap, char); 
printf("char %c\n", c); 
break; 

} 

va_end(ap); 

} 


STANDARDS 

T he va_start, va_arg, and va_end macros conform to ANSI C 3.159-1989 (ANSI C). 

COMPATIBILITY 

These macros are not compatiblewith the historic macros they replace. A backwards-compatible version can be found in the 
includefilevarargs.h. 

BUGS 

Unlike the varargs macros, thestdarg macros do not permit programmers to code a function with no fixed arguments. This 
problem generates work mainly when converting varargs code to stdarg code, but it also creates difficulties for variadic 
functionsthatwish to pass all of their argumentson to a function that takes a va_iist argument, such asvfprintf(3). 

BSD man page, 29 N ovember 1993 
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stdio 

stdio— Standard input/output library functions 

SYNOPSIS 

#include <stdio.h> 

FILE *stdin; 

FILE *stdout; 

FILE *stdem; 

DESCRIPTION 

The standard I/O library provides a simple and efficient buffered stream I/O interface. Input and output is mapped into 
logical data streams and the physical I/O characteristics are concealed. The functions and macros are listed in thissection; 
more information is avail able from theindividual man pages. 

A stream is associated with an external file (which may be a physical device) by opening a file, which may involve creating a 
new file. Creating an existing file causes its former contents to be discarded. If a file can support positioning requests (such as 
a disk file, as opposed to a terminal), then a file position indicator associated with the stream is positioned at the start of the 
file (byte zero), unless the file is opened with append mode. If append mode is used, the position indicator will be placed the 
end-of-file. The position indicator is maintained by subsequent reads, writes, and positioning requests. All input occurs as if 
the characters were read by successive cal Is to thet getc(3) function; all output takes place as if all characters were read by 
successive calls to thetputc(3) function. 

A file is disassociated from a stream by closing the file. Output streams are flushed (any unwritten buffer contents are 
transferred to the host environment) before the stream is disassociated from the file. The value of a pointer to a file object is 
indeterminate after a file isclosed (garbage). 

A file may be subsequently reopened, by the same or another program execution, and its contents reclaimed or modified (if it 
can be repositioned at the start). If the main function returns to its original caller, ortheexit(3) function is called, all open 
files are closed (hence all output streams are flushed) before program termination. Other methods of program termination, 
such as abort(3) do not bother about closing files properly. 

At program startup, three text streams are predefined and need not be opened explicitly: standard input (for reading 
conventional input), standard output (for writing conventional input), and standard error (for writing diagnostic output). 

T hese streams are abbreviated stdin, stdout, and stderr. W hen opened, the standard error stream is not fully buffered; the 
standard input and output streams are fully buffered if and only if thestreamsdo notto refer to an interactive device. 

0 utput streams that refer to terminal devices are always line buffered by default; pending output to such streams is written 
automatically whenever an input stream that refers to a terminal device is read. In cases where a large amount of computation 
is done after printing part of a line on an output terminal, it is necessary to ffiush(3) the standard output before going off 
and computing so that the output will appear. 

The stdio library is a part of the library nbc and routines are automatically loaded as needed by the compilers cc(l) and 
pc(l). The synopsis sections of the following manual pages indicate which include files are to be used, what the compiler 
declaration for the function looks like, and which external variables are of interest. 

The following are defined as macros; these names may not be reused without first removing their current definitions with 

#undef: BUFSIZ, EOF, FILENAME_MAX, FOPEN_MAX, L_cuserid, L_ctermid, L_tmpnam, NULL, SEEK END, SEEK_SET, SEE_CUR, TMPJIAX, 
clearerr, feof, terror, fileno, fropen, fwopen, getc, getchar, putc, putchar, stderr, stdin, stdout. Function versions Of the 
macro functions feof, terror, clearerr, fileno, getc, getchar, putc, and putchar exist and wi II be used if the macros 
definitionsareexplicitly removed. 

SEE ALSO 

open(2), close(2), read(2), write(2) 
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BUGS 

The standard buffered functions do not interact well with certain other library and system functions, especially vtork and 
abort. This may not be the case under Linux. 

STANDARDS 

Thestdio library conforms to ANSI C 3.159-1989 (ANSI C). 

LIST OF FUNCTIONS 

Function Description 


clearerr 

C heck and reset stream status 

fclose 

Close a stream 

fdopen 

Stream open functions 

feof 

C heck and reset stream status 

terror 

C heck and reset stream status 

ft lush 

Flush a stream 

fgetc 

Get next character or word from input stream 

fgetline 

Get alinefrom a stream 

fgetpos 

Reposition a stream 

fgets 

Get alinefrom a stream 

fileno 

C heck and reset stream status 

fopen 

Stream open functions 

fprintf 

Formatted output conversion 

fpurge 

Flush a stream 

fputc 

0 utput a character or word to a stream 

fputs 

Output a line to a stream 

tread 

Binary stream input/output 

freopen 

Stream open functions 

fropen 

0 pen a stream 

fscanf 

Input format conversion 

fseek 

Reposition a stream 

fsetpos 

Reposition a stream 

ftell 

Reposition a stream 

fwrite 

Binary stream input/output 

getc 

Get next character or word from input stream 

getchar 

G et next character or word from i nput stream 

gets 

Get alinefrom a stream 

getw 

G et next character or word from i nput stream 

mktemp 

M ake temporary filename (unique) 

perror 

System error messages 

printf 

Formatted output conversion 

putc 

0 utput a character or word to a stream 

putchar 

0 utput a character or word to a stream 

puts 

Output a line to a stream 

putw 

0 utput a character or word to a stream 



stpcpy 


remove 

rewind 

scant 

setbuf 

setbuffer 

setlinebuf 

setvbuf 

sprintf 

sscanf 

strerror 

sys_errlist 

sys_nerr 

tempnam 

tmpfile 

tmpnam 

ungetc 

vfprintf 

vfscanf 

vprintf 

vscanf 

vsprintf 

vsscanf 


Remove directory entry 
Reposition a stream 
Input form at conversion 
Stream buffering operations 
Stream buffering operations 
Stream buffering operations 
Stream buffering operations 
Formatted output conversion 
Input form at conversion 
System error messages 
System error messages 
System error messages 
T emporary file routines 
T emporary fileroutines 
Temporary fileroutines 
U n-get character from input stream 
Formatted output conversion 
Input form at conversion 
Formatted output conversion 
Input form at conversion 
Formatted output conversion 
Input form at conversion 
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stpcpy 

stpcpy— Copies a string returning a pointer to its end 

SYNOPSIS 

#include <string.h> 

char *stpcpy(char *dest , const char *src); 

DESCRIPTION 

Thestpcpyo function copies the string pointed to by src (including theterminating \e character) to thearray pointed to by 
dest . The strings may not overlap, and the destination string dest must be large enough to receive the copy. 

RETURN VALUE 

stpcpy o returns a pointer to the end of the string dest (that is, the address of theterminating null character) rather than the 
beginning. 

EXAMPLE 

For example, this program uses stpcpy to concatenate too and ban to produce tooban, which it then prints: 

#include <string.h> 


int 

main (void) 

{ 
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char *to = buffer; 
to = stpcpy (to, "foo"); 
to = stpcpy (to, "bar"); 
printf ("%s\n", buffer); 


C0NF0RMST0 

This function is not part of the AN SI or POSIX standards, and is not customary on U NIX systems, but is not a GN U 
invention either. Perhaps it comes from M S-DOS. 

SEE ALSO 

strcpy(3), bcopy(3), memccpy(3), memcpy(3), memmove(3) 

GNU, 3 September 1995 


strcasecmp, strncasecmp 

strcasecmp, strncasecmp —Compare two strings, ignoring case 

SYNOPSIS 

#include <string.h> 

int strcasecmp(const char *sl, const char *s2); 

int strncasecmp(const char *sl, const char *s2, size_t n); 


DESCRIPTION 

The strcasecmp o function compares the two strings si and s 2, ignoring the case of the characters. It returns an integer less 
than, equal to, or greater than zero if si is found, respectively, to be I ess than, to match, or be greater than s 2 . 

T he strncasecmp) ) function is similar, except it only compares thefirst n characters of s l . 

RETURN VALUE 

The strcasecmp o and strncasecmp) ) functions return an integer less than, equal to, or greater than zero if si (or the first n 
bytes thereof) is found, respectively, to be less than, to match, or be greater than s 2. 

conforms™ 

BSD 4.3 


SEE ALSO 

bcmp(3), memcmp(3), strcmp(3), strcoll(3), strncmp(3) 


11 April 1993 


strcat, strncat 

strcat, strncat— Concatenate two strings 

SYNOPSIS 


#include <string.h> 

char *strcat(char *dest , const char *src); 

char *strncat(char *dest , const char *src, size_t n); 



strcmp, strncmp 



DESCRIPTION 

Thestrcato function appends the s re string to thedest string, overwriting the \e character at the end of dest , and then 
adds a terminating \a character. The strings may not overlap, and thedest string must have enough space for the result. 

T he strncat () function is similar, except that only thefirst n characters of s r c are appended to dest. 

RETURN VALUE 

Thestrcato and strncat () functions return a pointer to the resulting string dest. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

bcopy(3), memccpy(3), memcpy(3), strcpy(3), strncpy(3) 

GNU, 11 April 1993 


strehr, strrehr 

strehr, strrehr— Locate character in string 

SYNOPSIS 

#include <string.h> 

char *strchr(const char *s,int c); 

char *strrchr(const char *s,int c); 

DESCRIPTION 

Thestrchro function returns a pointer to the first occurrence of the character c i n the stri ng s . 

T he strrehr) ) function returns a pointer to the last occurrence of the character c in the string s . 

RETURN VALUE 

T he strehr <) and strrchr( ) functions return a pointer to the matched character or null if the character is not found. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

index(3), memchr(3), rindex(3), strpbrk(3), strsep(3), strspn(3), strstr(3), strtok(3) 

12 April 1993 


strcmp, strncmp 

strcmp, strncmp — Compare two strings 

SYNOPSIS 


#include <string.h> 

int strcmp(const char *sl, const char *s2); 

int strncmp(const char *sl, const char *s2, size_t n); 
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DESCRIPTION 

The strcmp( ) function compares the two strings si and s 2 .lt returns an integer less than, equal to, or greater than zero if si 
is found, respectively, to be less than, to match, or be greater than s 2 . 

The strncmp( ) function issimilar, except it only compares the firstn characters of si. 

RETURN VALUE 

The strcmpf ) and strncmpo functions return an integer less than, equal to, or greater than zero if si (or thefirst n bytes 
thereof) isfound, respectively, to belessthan, to match, or be greater than s 2 . 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

bcmp(3), memcmp(3), strcasecmp(3), strncasecmp(3), strcoll(3) 

11 April 1993 


strcoll 

strcoii — C ompares two stri ngs usi ng the current locale 

SYNOPSIS 

#include <string.h> 

int strcoll(const char *sl, const char *s2); 

DESCRIPTION 

The strcoii 0 function compares the two stri ngs si and s 2 . It returns an integer less than, equal to, or greater than zero if si 
isfound, respectively, to belessthan, to match, or be greater than s 2 . The comparison is based on strings interpreted as 
appropriate for the program's current locale for category lc_collate. (See setiocaie(3)). 

RETURN VALUE 

Thestrcoiio function returns an integer less than, equal to, or greater than zero if si isfound, respectively, to belessthan, 
to match, or be greater than s 2 , when both are interpreted as appropriate for the current locale. 

C0NF0RMST0 

SVID 3, BSD 4.3, ISO 9899 

NOTES 

The Linux C Library currently hasn't implemented the complete POSIX-collating. 

In thePOSIX orC locales, strcoiio is equivalent to strcmpo. 

SEE ALSO 

bcmp(3), memcmp(3), strcasecmp(3), strcmp(3), strxf rm(3), setlocale(3) 

GNU, 12 April 1993 


strcpy, strncpy 

strcpy, strncpy— C opy a string 



strdup 


1031 


SYNOPSIS 

#include <string.h> 

char *strcpy(char *dest , const char *src); 

char *strncpy(char *dest , const char *src, size_t n); 

DESCRIPTION 

T he strcpy () function copies the string pointed to be s r c (including theterminating \e character) to thearray pointed to by 
dest . The strings may not overlap, and the destination string dest must be large enough to receive the copy. 

T he strncpy () function is similar, except that not more than n bytes of s r c are copied. Thus, if there is no null byte among 
thefirstn bytes of src, the result will not be null-terminated. 

In the case where the length of src is I ess than that of n, the remainder of dest will be padded with nulls. 

RETURN VALUE 

The strcpy o and strncpy () functions return a pointer to the destination string dest. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

bcopy(3), memccpy(3), memcpy(3), memmove(3) 

GNU, 11 April 1993 


strdup 

strdup— D uplicates a string 

SYNOPSIS 

#include <string.h> 

char *strdup(const char *s); 

DESCRIPTION 

The strdup o function returns a pointer to a new string that is a duplicate of the strings. M emory for the new string is 
obtained with maiioc(3), and can be freed with tree(3). 

RETURN VALUE 

T he strdupi ) function returns a pointer to the duplicated string, orNun if insufficient memory was available. 

ERRORS 

enomem Insufficient memory availableto allocate duplicate stri ng 

C0NF0RMST0 

SVID 3, BSD 4.3 

SEE ALSO 

calloc(3), malloc(3), realloc(3), free(3) 


GNU, 12 April 1993 
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strerror 

strerror— Returns string describing error code 

SYNOPSIS 

#include <string.h> 
char *strerror(int errnum); 

DESCRIPTION 

The strerror o function returns a string describing the error code passed in the argument errnum. The string can only be 
used until the next call to strerroro. 

RETURN VALUE 

The strerroro function returns the appropriate description string, or an unknown error message if the error code is 
unknown. 

C0NF0RMST0 

SVID 3, PO SIX, BSD 4.3, ISO 9899 

SEE ALSO 

errno(3), perror(3), strsignal(3) 

GNU, 13 April 1993 


strfry 

strtry — Randomizes a string 

SYNOPSIS 

#include <string.h> 
char *strfry(char *string); 

DESCRIPTION 

The strt ry( ) function randomizes the contents of stri ng by using rand(3) to randomly swap characters in the string. The 
result is an anagram ofstri ng. 

RETURN VALUE 

The strt ry( ) function returnsa pointer to therandomized string. 

C0NF0RMST0 

The strtryo function is unique to the Linux C Library and GN U C Library. 

SEE ALSO 

memfrob(3) 

GNU ,12 April 1993 
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strttime — Formats date and time 



strftime 

SYNOPSIS 

#include <time.h> 

size t strftime (char *s , size_t max, const char *format, 
const struct tm *t m) ; 

DESCRIPTION 

The strftime o function formats the broken-down timet m according to the format specification format and places the result 
i n th e ch aracter array s of si ze ma x. 

Ordinary characters placed in the format string are copied to s without conversion. Conversion specifiers are introduced by a 
% character, and are replaced in s as follows: 

%a The abbreviated weekday name according to the current locale 

%a Thefull weekday name according to the current locale 

%b The abbreviated month name according to the current locale 

%b Thefull month nameaccordingto thecurrent locale 

%c Thepreferred date and time representation for thecurrent locale 

%d T he day of the month as a decimal number (range 01 to 31) 

%h The hour as a decimal number using a 24-hour clock (range 00 to 23) 

%i The hour as a decimal number using a 12-hour clock (ranged to 12) 

%j The day of the year as a decimal number (range 001 to 366) 

%m The month as a decimal number (ranged to 12) 

%m The minute as a decimal number 

%p Either a. m. or p.m. according to the given time value, or the corresponding strings for the current 

locale 

%s The second as a decimal number 

%u The week number of the current year as a decimal number, starting with the first Sunday as the first 

day of the first week 

%w The week number of thecurrent year as a decimal number, starting with the first M onday as the first 

day of the first week 

%w The day of the week as a decimal, Sunday being 0 

%x Thepreferred date representation forthecurrent locale without the ti me 

%x Thepreferred time representation forthecurrent locale without the date 

%y T he year as a deci mal number without a century (range 00 to 99) 

%y The year as a deci mal number including the century 

%z The time zone or name or abbreviation 

%% A literal % character 

The broken-down time structure tm is defined in <time.h> as follows: 

struct tm 
{ 

int tm sec; /* seconds */ 

int tm min; /* minutes */ 

int tm hour; /* hours */ 

int tm mday; /* day of the month */ 

int tm mon; /* month */ 

int tm year; /* year */ 

int tm wday; /* day of the week */ 

int tm yday; /* day in the year */ 

int tm isdst; /* daylight saving time */ 

}; 
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The members of the tm structure are 

tm_sec T he number of seconds after the minute, normally in the range 0 to 59, but can be up to 

61 to allow for leap seconds. 

tm_min T he number of minutes after the hour, in the range 0 to 59. 

tm_hour T he number of hours past midnight, in the range 0 to 23. 

tm_mday T he day of the month, in the range 1 to 31. 

tm_mon T he number of monthssincej anuary, in the range 0 to 11. 

tm_year T he number of years since 1900. 

tm_wday T he number of days si nee Sunday, in the range 0 to 6. 

tm_yday T he number of days sincej anuary 1, in the range 0 to 365. 

tm_isdst A flag that indicates whether daylight saving time is in effect at the time described. The 

value is positive if daylight saving time is in effect, zero if itisnot, and negative if the 
information is not available. 

RETURN VALUE 

T he strftime( ) function returns the number of characters placed in the array s, not including the terminating null character. 
If the value equals max, it means that the array was too small. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

date(l), time(2), ctime(3), setlocale(3), sprintf(3) 

NOTES 

Thefunction supports only those locales specified in iocaie(7) 

GNU, 2]ulyl993 

streaseemp, streat, strehr, stremp, strcoll, strepy, strespn, 
strdup, strf ry, strlen, strncat, strnemp, strnepy, strncasecmp, 
strpbrk, strrehr, strsep, strspn, strstr, strtok, strxf rm, 
index,rindex 

streaseemp, streat, strehr, stremp, strcoll, strepy, strespn, strdup, strfry, strlen, strncat, strnemp, strnepy, strncasecmp, 
strpbrk, strrehr, strsep, strspn, strstr, strtok, strxfrm, index, rindex —String operations 

SYNOPSIS 

#include <string.h> 

int strcasecmp(const char *sl, const char *s2); 
char *strcat(char *dest, const char *src); 
char *strchr(const char *s,int c); 
int strcmp(const char *sl, const char *s2); 
int strcoll(const char *sl, const char *s2); 
char *strcpy(char *dest , const char *src); 
size_t strcspn(const char *s, const char *reject); 
char *strdup(const char *s); 




strpbrk 



char *strfry(char *string); 
size_t strlen(const char *s); 

char *strncat(char *dest , const char *src, size_t n); 

int strncmp(const char *sl, const char *s2, size_t n); 

char *strncpy(char *dest , const char *src, size_t n); 

int strncasecmp(const char *sl, const char *s2, size_t n); 

char *strpbrk(const char *s, const char *accept); 

char *strrchr(const char *s,int c); 

char *strsep(char **stringp, const char *delim); 

size_t strspn(const char *s, const char *accept); 

char *strstr(const char *haystack, const char *needle); 

char *strtok(char *s, const char *delim); 

size_t strxfrm(char *dest , const char *src, size_t n); 

char *i ndex (const char*"s,i nt c); 

char *rindex(const char *s,int c); 


DESCRIPTION 

The string functions perform string operations on Nun-terminated strings. Seethe individual man pages for descriptions of 
each function. 

SEE ALSO 

index(3), rindex(3), strcasecmp(3), strcat(3), strchr(3), strcmp(3), strcoll(3), strcpy(3), strcspn(3), strdup(3), strfry(3), 
strlen(3), strncat(3), stnncmp(3), strncpy(3), strncasecmp(3), strpbrk(3), strrchr(3), strsep(3), strspn(3), strstn(3), 
strtok(3), strxfrm(3) 

9 April 1993 


strlen 

strien— Calculates the length of a string 

SYNOPSIS 

#include <string.h> 
size_t strlen(const char *s); 

DESCRIPTION 

The strien() function calculates the length of the stri ng s, not including the terminating \e character. 

RETURN VALUE 

The strien() function returns the number of characters ins. 

C0NF0RMST0 

SVID 3, PO SIX, BSD 4.3, ISO 9899 

SEE ALSO 

string(3) 

12 April 1993 


strpbrk 

strpbrk— Searches a string for any of a set of characters 
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SYNOPSIS 

#include <string.h> 

char *strpbrk(const char *s, const char *accept); 

DESCRIPTION 

The strpbrk () function locates the first occurrence in the string s of any of the characters in thestringaccept. 

RETURN VALUE 

The strpbrk () function returns a pointer to the character in s that matches one of the characters in accept. 

C0NF0RMST0 

SVID 3, PO SIX, BSD 4.3, ISO 9899 

SEE ALSO 

index(3), memchr(3), rindex(3), strchr(3), strsep(3), strspn(3), strstr(3), strtok(3) 

12 April 1993 


strptime 

strptime—Converts a string representation of time to a timetm structure 

SYNOPSIS 

#include <time.h> 

char *strptime(char *buf , const char *format , const struct tm *tm); 

DESCRIPTION 

strptime o isthe complementary function to strftimeo and converts the character string pointed to by buf to atime value, 
which is stored in thetm structure pointed to bytm, using the format specified by f or mat. format isa character string that 
consists of field descriptors and text characters, reminiscent of scant(3). Each field descriptor consists of a % character 
followed by another character that specifies the replacement for the field descriptor. All other characters are copied from 
f or mat into the result. T he followi ng field descriptors are supported: 

%% Same as %. 

%a, %a Day of week, using locale's weekday names; either the abbreviated or full name may be 

specified. 

%b, %b, %h M onth, using locale's month names; either the abbreviated or full name may be 

specified. 

%c Date and time as %x, %x. 

%c Date and time, in locale's long-format date and time representation. 

%d, %e Day of month (1-31; leading zeroes are permitted but not required). 

%d Dateas%m/%d/%y. 

%h, %k Hour (0-23; leading zeroes are permitted but not required). 

%i, %i Hour (0-12; leading zeroes are permitted but not required). 

%j Day number of year (001-366). 

%m Month number (1-12; leading zeroes are permitted but not required). 

%m M inute (0-59; leading zeroes are permitted but not required). 

%p Locale's equivalent of a.m. or p.m. 

%r Timeas%i:%M:%s %p. 
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%r Timeas%H:%M. 

%s Seconds (0-61; leading zeroes are permitted but not required; extra second allowed for 

leap years). 

%t Timeas%H:%M:%s. 

%w W eekday number (0-6) with Sunday as the first day of the week. 

%x Date, using locale's date format. 

%x Time, using locale's time format. 

%y Yearwithin century (0-99; leading zeroes are permitted but not required. 

Unfortunately, this makes the assumption that we are stuck in the 20th century, as 
1900 is automatically added onto this number for the tm year field.) 

%y Year, including century (for example, 1988). 

Caseisignored when matching items such as month or weekday names. 

The broken-down time structure tm is defined in <time.h> asfollows: 

struct tm 

{ 

int tm_sec; /* seconds */ 

int tm_min; /* minutes */ 

int tm_hour; /* hours */ 

int tm_mday; /* day of the month */ 

int tm_mon; /* month */ 

int tm_year; /* year */ 

int tm_wday; /* day of the week */ 

int tm_yday; /* day in the year */ 

int tm_isdst; /* daylight saving time */ 

}; 

RETURN VALUE 

The strptime( ) function returns a pointer to the character following the last character in the string pointed to by buf. 

SEE ALSO 

strftime(3), time(2), setlocale(3), scanf(3) 

BUGS 

The return values point to static data, whose contents are overwritten by each call. 

NOTES 

This function is only available in libraries newer than version 4.6.5. 

Thefunction supports only those locales specified in iocaie(7). 

GNU, 26 September 1994 


strsep 

strsep— Extracts token from string 

SYNOPSIS 


#include <string.h> 

char *strsep(char **stringp, const char *delim); 
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DESCRIPTION 

Thestrsepo function returns the next token from the string s t r i ngp which is delimited by del i m. Thetoken is terminated 
with a \0 character and stri ngp is updated to point past thetoken. 

RETURN VALUE 

Thestrsepo function returns a pointer to thetoken, or null if deiim is not found in stri ngp. 

C0NF0RMST0 

BSD 4.3 


SEE ALSO 

index(3), memchr(3), rindex(3), strchr(3), strpbrk(3), strspn(3), strstr(3), strtok(3) 


GNU, 12 April 1993 


strsignal 

strsignai— Returns string describing signal 

SYNOPSIS 

#include <string.h> 

char *strsignal(int sig); 

extern const char * const syssigli st [] 

DESCRIPTION 

The strsignai) ) function returns a string describing the signal number passed in the argument s i g. The string can only be 
used until the next call to strsignai)). 

T he array sys.si gi i st holds the signal description strings indexed by signal number. 

RETURN VALUE 

The strsignai)) function returns the appropriate description string, or an unknown signal message if the signal number is 
invalid. 

SEE ALSO 

psignal(3), strerror(3) 

GNU, 13 April 1993 


strspn, strcspn 

strspn, strcspn— Search a string for a set of characters 

SYNOPSIS 

#include <string.h> 

size t strspn(const char *s, const char *accept); 
size t strcspn(const char *s, const char *reject); 

DESCRIPTION 

The strspn)) function calculates the length of the initial segment of s, which consists entirely of characters in accept. 

The strcspn)) function calculates the length of the initial segment of s , which consists entirely of characters not in rej ect. 
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RETURN VALUE 

The strspn( ) function returns the number of characters in the initial segment of s, which consist only of characters from 

accept. 

The strcspn( ) function returns the number of characters in the initial segment of s , which are not in the string r ej ect. 

C0NF0RMST0 

SVID 3, PO SIX, BSD 4.3, ISO 9899 

SEE ALSO 

index(3), memchr(3), rindex(3), strchr(3), strpbrk(3), strsep(3), strstr(3), strtok(3) 

12 April 1993 


strstr 

strstr— Locates a substring 

SYNOPSIS 

#include <string.h> 

char *strstr(const char *haystack, const char *needle); 

DESCRIPTION 

Thestrstro function finds the first occurrence of the substring need i e in the string hay stack. The terminating \e characters 
are not compared. 

RETURN VALUE 

Thestrstro function returns a pointer to the beginning of the substring, or null if the substring is not found. 

SEE ALSO 

index(3), memchr(3), rindex(3), strchr(3), strpbrk(3), strsep(3), strspn(3), strtok(3) 

GNU, 12 April 1993 


strtod 

strtod— Converts ASCI I string to double 

SYNOPSIS 

#include <stdlib.h> 

double strtod(const char *nptr, char **endptr); 

DESCRIPTION 

The strtod o function converts the initial portion of the string pointed to by nptr to double representation. 

The expected form of the string is optional leading whitespace as checked by isspace(3), an optional plus (+) or minus sign 
(-) followed by a sequence of digits optionally containing a decimal point character, optionally followed by an exponent. An 
exponent consists of an e ore, followed by an optional plus or minus sign, followed by a nonempty sequence of digits. If the 
locale is note orPOSIX, different formats may be used. 
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RETURN VALUES 

T he strtod function returns the converted value, if any. 

If end pt r is not null, a pointer to the character after the last character used in the conversion is stored in the location 
referenced byendptr. 

If no conversion is performed, zero is returned and the value of n pt r is stored in the location referenced byendptr. 

If the correct value would cause overflow, plusorminusHUGE_vAL is returned (accordingto the sign of thevalue), and erange 
is stored in er r no . If the correct value would cause underflow, zero is returned and erange is stored in errno. 

ERRORS 

erange Overflow or underflow occurred. 


C0NF0RMST0 

ANSI C 

SEE ALSO 

atof(3), atoi(3), atol(3), strtol(3), strtoul(3) 


BSD man page, 4 M arch 1996 


strtok 

strtok — Extracts token from string 

SYNOPSIS 

#include <string.h> 

char *strtok(char *s , const char *delim); 

DESCRIPTION 

A token is a nonempty string of characters not occurring in the string del i m, followed by \e or by a character occurring in 

del i m. 

T he strtok () function can be used to parse the strings into tokens. Thefirst call to strtok) ) should haves as its first 
argument. Subsequent calls should have the first argument set to null. Each call returns a pointer to the next token, or null 
when no more tokens are found. 

If a token ends with a delimiter, this delimiting character is overwritten with a \b and a pointer to the next character is saved 
for the next call to strtok. The delimiter string del i m may be different for each call. 

BUGS 

This function modifies its first argument. The identity of the delimiting character is lost. 

RETURN VALUE 

T he strtok () function returns a pointer to the next token, or null if there are no more tokens. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

index(3), memchr(3), rindex(3), strchr(3), strpbrk(3), strsep(3), strspn(3), strstr(3) 


GNU, 10 February 1996 
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strtol 

strtoi — C onverts a string to a long integer 

SYNOPSIS 

#include <stdlib.h> 

long int strtol(const char *nptr, char **endptr,int base); 

DESCRIPTION 

The strtoi o function converts the string in nptr to a long integer value according to the given base, which must be between 
2 and 36 inclusive, or be the special valueO. 

The string must begin with an arbitrary amount of whitespace (as determined by isspace(3)) followed by a single optional + 
or - sign. If base iszero or 16, thestring may then include a ax prefix, and the number will be read in base 16; otherwise, a 
zero base is taken as 10 (decimal) unless the next character isO, in which case it is taken as 8 (octal). 

The remainder of thestring is converted to a long int value in the obvious manner, stopping at the first character that is not 
a valid digit in the given base. (I n bases above 10, the letter a in either upper- or lowercase represents 10, b represents 11, and 
so forth, with z representing 35.) 

If endptr is not null, strtoio stores the address of the first invalid character in *endptr. If there were no digits at all, strtoi o 
stores the original value of nptr in *endptr. (Thus, if *nptr is not \a but **endptr is\e on return, the entire string is valid.) 

RETURN VALUE 

The strtoio function returns the result of the conversion, unless the value would underflow or overflow. If an underflow 
occurs, strtoio returns long_min. If an overflow occurs, strtoio returns longjiax. In both cases, err no is set to erange. 

ERRORS 

erange Thegiven stringwasout of range; the value converted hasbeen clamped. 

C0NF0RMST0 

SVID 3, BSD 4.3, ISO 9899 

SEE ALSO 

atof(3), atoi(3), atol(3), strtod(3), strtoul(3) 

BUGS 

Ignores the current locale 

GNU, 10 Junel995 


strtoul 

strtoui— Converts a string to an unsigned long integer. 

SYNOPSIS 


#include <stdlib.h> 

unsigned long int strtoul(const char *nptr, char **endptr, 
int base); 
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DESCRIPTION 

Thestrtouio function converts the string in nptr to an unsigned long integer value according to the given base, which must 
be between 2 and 36 inclusive, or be the special value 0. 

The string must begin with an arbitrary amount of whitespace (as determined by isspace(3)) followed by a single optional + 
or - sign. If base is zero or 16, the string may then include a ax prefix, and the number will be read in base 16; otherwise, a 
zero base is taken as 10 (decimal) unless the next character is 0, in which case it is taken as 8 (octal). 

The remainder of the string is converted to an unsigned long int value in the obvious manner, stopping at the first character 
that is not a valid digit in the given base. (I n bases above 10, the letter a in either upper- or lowercase represents 10, b 
represents 11, and so forth, with z representing 35.) 

If endptr is not null, strtouio stores the address of the first invalid character in *endptr. If there were no digits at all, 
strtouio stores the original value of nptr in *endptr. (Thus, if *nptr is not \e but **endptr is\o on return, the entire string is 
invalid.) 

RETURN VALUE 

Thestrtouio function returns either the result of the conversion or, if there was a leading minus sign, the negation of the 
result of the conversion, unless the original (non-negated) valuewould overflow; in the latter case, strtouio returns 
ulong_max and sets the global variableer r no to erange. 

ERRORS 

erange The given string was out of range; the value converted has been clamped. 

C0NF0RMST0 

SVID 3, BSD 4.3, ISO 9899 

SEE ALSO 

atof(3), atoi(3), atol(3), strtod(3), strtol(3) 

BUGS 

strtoui ignores the current locale. 

GNU, 29 M arch 1993 


strxfrm 

strxt rm— String transformation 

SYNOPSIS 

#include <string.h> 

size t strxfrm(char *dest , const char *src, size_t n); 

DESCRIPTION 

T he strxtrm( > function transforms thes re string into aform such that the result of strempo on two strings that have been 
transformed with strxfrm o is the same as the result of strcoiio on the two strings before their transformation. T hefirst n 
characters of the transformed string are placed in dest . The transformation is based on the program's current locale for 
category lc_collate. (See setiocaie(3)). 

RETURN VALUE 

The strxfrmi > function returns the number of bytes required to store the transformed string in dest excluding the terminat¬ 
ing \@ character. If the value returned is n or more the contents of dest are indeterminate. 
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CONFORMSTO 

SVID 3, BSD 4.3, ISO 9899 

NOTES 

The Linux C Library currently hasn't implemented the complete PO SIX-collating. 

In thePOSIX orC locales strxfrmo is equivalent to copying the string with strncpyo. 

SEE ALSO 

bcmp(3), memcmp(3), strcasecmp(3), strcmp(3), strcoll(3), setlocale(3) 

GNU, 12 April 1993 


swab 

swab— Swaps adjacent bytes 

SYNOPSIS 

#include <string.h> 

void swab(const void *from, void*to, size_t n); 

DESCRIPTION 

Theswabo function copiesn bytesfrom thearray pointed to by from to thearray pointed to by to, exchanging adjacent a/en 
and odd bytes. Thisfunction isused to exchange data between machines that have different low/high byteordering. 

RETURN VALUE 

Theswabo function returns no value. 

conforms™ 

SVID 3, BSD 4.3 

SEE ALSO 

bstring(3) 

GNU, 13 April 1993 


sysconf 

sysconf— Gets configuration information at runtime 

SYNOPSIS 

#include <unistd.h> 
long sysconf(int name); 

DESCRIPTION 

sysconf o provides a way for the application to determine values for system limits or options at runtime 

Theequivalent macros defined in <unistd.h> can only give conservative values; if an application wants to take advantage of 
values that may change, a call to sysconf o can be made, which may yield more liberal results 

Forgetting information about a particular file, seefpathconfo or pathconfo. 

The foil owing values are supported for name. First, the PO SIX. Incompatible values: 
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_SC_ARG_MAX 

_SC_CHILD_MAX 

_SC_CLK_TCK 

_SC_STREAM_MAX 

_SC_TZNAME_MAX 
_SC_OPEN_MAX 
_SC_JOB_CONTROL 
_SC_SAVED IDS 
_SC_VERSION 

N ext, the PO SIX.2 values: 

_SC_BC_BASE_MAX 
_SC_BC_DIM_MAX 
_SC_BC_SCALE_MAX 
_SC_BC_STR I NG_MAX 
_SC_COLL_WEIGHTS_MAX 

_SC_EXPR_NEST_MAX 

_SC_LINE_MAX 

_SC_RE_DUP„MAX 

_SC_2_VERSI0N 

_SC_2_DEV 

_SC_2_F0RT_DEV 

_SC_2_F0RT_RUN 


Themaximum length of the arguments to theexeco family of 
functions; the corresponding macro isARG_MAx. 

The number of simultaneous processes per user ID; the corresponding 
macro is_Posix_cHiLD_MAx. 

The number of clock ticks per second; the corresponding macro is 

CLK_TCK. 

The maximum number of streams that a process can have open at any 
time. The corresponding POSIX macro Isstream_max; the 
corresponding standard C macro Isfopen_max. 

Themaximum number of bytes in a time zone name; the 
corresponding macro Istzname_max. 

Themaximum number of files that a process can have open at any 
time; the corresponding macro Is_posix_open_max. 

Thisindicates whether POSIX-stylejob control is supported, the 
corresponding macro is_Posix_joB_coNTROL. 

Thisindicates whether a process has a saved set-user-1 D and asaved 
set-group-1 D; the corresponding macro Is_posix_saved_ids. 

Indicates the year and month thePOSIX.1 standard was approved in 
theformatYYYYHML; the value 199009 L indicates the most recent 
revision, 1990. 


Indicates themaximum obase value accepted by the bc(l) utility; the 
corresponding macro isBC BASEj/iAx. 

Indicates themaximum value of elements permitted in an array by 
bc(l); the corresponding macro isBc_DiM_MAx. 

Indicates themaximum scalevalue allowed by bc(l); the 
corresponding macro Isbc_scale_max. 

Indicates themaximum length of a string accepted by bc(l); the 
corresponding macro Isbc_string_max. 

Indicates themaximum numbers of weights that can be assigned to an 
entry of the lc_collate order keyword in the locale definition file; the 
corresponding macro iscoLL_wEiGHTs_MAx. 

Is the maximum number of expressionsthat can be nested within 
parentheses by expr(l). The corresponding macro Isexpr_nest_max. 
Themaximum length of a utility's input line length, either from 
standard input or from a file. This includes length for a trailing 
newline The corresponding macro Isline_max. 

T he maximum number of repeated occurrences of a regular 
expression when theinterval notation \{m,n\} isused. Thevalueof 
the corresponding macro isREj>up_MAx. 

Indicates the version of the PO SI X .2 standard in theformatof 
yyyymml. Thecorresponding macro isposix2_vERsioN. 

Indicates whether the POSIX.2 C language development facilities are 
supported. Thecorresponding macro isposix 2 _c dev. 

Indicates whether the POSIX.2 FORTRAN development utilities are 
supported. Thecorresponding macro isposix2_FORT run. 

Indicates whether the POSIX.2 FORTRAN runtimeutilitiesare 
supported. Thecorresponding macro Isposix2_fort_run. 
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posix2_localedef I ndicates whether the PO SI X .2 creation of locates via iocaie(l) is 

supported. The corresponding macro isposix2_LocALEDEF. 
_sc_2_sw_dev Indicates whether the PO SIX.2 software development utilities option 

is supported. The corresponding macro isposix2_sw_DEv. 

RETURN VALUE 

The value returned is the value of the system resource, i if a queried option is available 0 if it is not, or-i on error. The 
variableerrno is not set. 

C0NF0RMST0 

POSIX.1, proposed POSIX.2 

BUGS 

It is difficult use arg_max because it is not specified how much of the argument space for execo is consumed by the user's 
environment vari ables. 

Some returned values may be huge; they are not suitable for allocating memory. 

POSIX.2 is not yet an approved standard; the information in this man page is subject to change. 

SEE ALSO 

bc(l), expn(l), locale(l), fpathconf( 3 ), pathconf( 3 ) 

GNU, 18 April 1993 


closelog,openlog,syslog 

cioseiog, openlog, syslog— Send messages to the system logger 

SYNOPSIS 

#include <syslog.h> 

void openlog( char *ident ,int option,int facility); 
void syslog( int priority, char *format, ...); 
void closelog( void ); 

DESCRIPTION 

cioseiogi ) closes the descriptor being used to write to the system logger. The use of cioseiog o isoptional. 

openlogo opens a connection to the system logger for a program. T he string pointed to by i dent isadded to each message, 
and is typically set to the program name Values for opt i on and facility are given in the next subsection. The use of 
openlog o isoptional; itwill automatically be called by sysiogo if necessary, in which case i dent will default to null. 

syslog o generates a log message, which will be distributed by sysiogd(8). pri ori ty is a combination of the f aci i i ty and the 
i evei , values for which are given in the next subsection. The remaining arguments are a for mat , as in printt(3) and any 
arguments required by thef or mat , except that the two characters %m will be replaced by the error message string (stren-or) 
correspond! ng to the present value of er r no. 

PARAMETERS 

This section lists the parameters used to set the values of opt; on, f aci i i t y , and priority. 
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OPTION 

The option argument to openiogo isan or of any of these: 

log_cons Write directly to system console if there is an error while sending to system logger 

log_ndelay Open the connection immediately (normally, theconnection is opened when the 

first message is logged) 
log_perror Print to stdem as wel I 

log_pid I nclude pid with each message 


FACILITY 

Thefacility argument isused to specify what type of program is logging the message. T his lets the confi guration file specify 
that messages from different facilities will be handled differently. 


LOG_AUTH 

Security/authorization messages (deprecated use log_authpriv 
instead) 

LOG_AUTHPRIV 

Security/authorization messages (private) 

LOG_CRON 

C lock daemon (cron and at) 

LOG_DAEMON 

Other system daemons 

LOG_KERN 

Kernel messages 

log_localo through 

L0G_L0CAL7 

Reserved for local use 

LOG_LPR 

Line printer subsystem 

L0G_MAIL 

M ail subsystem 

LOG_NEWS 

Usenet news subsystem 

LOG_SYSLOG 

M essages generated internally by sysiogd 

logjjser (default) 

Generic user-level messages 

LOG_UUCP 

UUCP subsystem 


LEVEL 

T his determines the importance of the message. The levels, in order of decreasing importance, are 


L0G_EMERG 

System is unusable 

L0G_ALERT 

Action must betaken immediately 

L0G_CRIT 

Critical conditions 

L0G_ERR 

Error conditions 

LOG_WARNING 

Warning conditions 

LOG_NOTICE 

Normal, but significant, condition 

LOG_INFO 

Informational message 

L0G_DEBUG 

Debug-level message 


HISTORY 

A sysiog function call appeared in BSD 4.2. 

SEE ALSO 

logger(l), sysiog.conf(5), syslogd(8) 


Linux, 15 February 1994 
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system 

system— Executes a shell command 

SYNOPSIS 

#include <stdlib.h> 

int system (const char * string); 

DESCRIPTION 

system)) executes a command specified in string by calling /bin/sh -c stri ng, and returns after the command has been 
completed. D uring execution of the command, sigchld will be blocked, and sigint and sigquit will be ignored. 

RETURN VALUE 

The value returned is 127 if theexecve)) call for /bin/sh fails, -1 iftherewas another error, and the return codeofthe 
command otherwise. 

If the valueof string is null, system)) returns non-zero if the shell is available, and zero if not. 
system) ) does not affect the wait status of any other children. 

C0NF0RMST0 

ANSI C, POSIX.1, proposed POSIX.2, BSD 4.3 

BUGS 

Do not use system)) from a program with suid or sgid privileges, because strange values for some environment variables 
might be used to subvert system integrity. U setheexec(2) family of functions instead, but not execip(2) or execvp(2). 

The check for the avail ability of /bin/sh is not actually performed; it is always assumed to be available. 

It is possible for the shell command to return 127 , so that code is not a sure indication that theexecve)) call failed; check 
err no to make sure 

SEE ALSO 

sh( 1), exec(2), signal(2) 

GNU, 13 April 1993 


tan 

tan— Tangent function 

SYNOPSIS 

#include <math.h> 
double tan(double x); 

DESCRIPTION 

Thetano function returns the tangent of *, where* is given in radians. 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 
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SEE ALSO 

acos(3), asin(3), atan(3), atan2(3), cos(3), sin(3) 


8Junel993 


tanh 

tanh— H yperbolic tangent function 

SYNOPSIS 

#include <math.h> 
double tanh(double x); 

DESCRIPTION 

T he tanh o function returns the hyperbolic tangent of *, which is defined mathematically assinh(x) / cosh(x). 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

acosh(3), asinh(3), atanh(3), cosh(3), sinh(3) 

13Junel993 


telldir 

teiidir— Returnscurrent location in directory stream 

SYNOPSIS 

#include <dirent.h> 
off t telldir(DIR *dir); 

DESCRIPTION 

The teiidir o function returns the current location associated with the directory stream dir. 

RETURN VALUE 

T he teiidir)) function returns the current location in the directory stream or -i if an error occurs. 

ERRORS 

ebadf Invalid directory stream descriptor di r 

C0NF0RMST0 

BSD 4.3 

SEE ALSO 

opendir(3), readdir(3), closedir(3), rewinddir(3), seekdir(3), scandir(3) 
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termios tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow, cfmakeraw, cfgetospeed, cfgetipeed, 

cfsetispeed, cfstogaeed, tcgetpg-p, tcsetpgrp 



tempnam 

tempnam— C reates a name for a temporary file 

SYNOPSIS 

#include <stdio.h> 

char *tempnam(const char *dir, const char *pfx); 

DESCRIPTION 

The tempnam() function generates a unique temporary filename using up to five characters of pf x, if it is not null. The 
directory to placethefileissearched forin the following order: 

1. Thedirectory specified by theenvironment variableTMPDiR, if itiswritable 

2. The directory specified by the argument di r, if it is not null 

3. Thedirectory specified by p tmpdir 

4. Thedirectory \tmp 

The storage for the filename is allocated by maiioco, and so can be freed by the function freed. 

RETURN VALUE 

The tempnamo function returns a pointer to the unique temporary filename, or null if a unique filename cannot be 
generated. 

ERRORS 

eexist Unable to generate a unique filename 

C0NF0RMST0 

SVID 3, BSD 4.3 

SEE ALSO 

mktemp(3), mkstemp(3), tmpnam(3), tmpfile(3) 

GNU, 3 April 1993 

termios, tcgetattr, tcsetattr, tcsendbreak,tcdrain,tcflush, 
tcflow, cfmakeraw, cfgetospeed,cfgetispeed,cfsetispeed, 
cfsetospeed, tcgetpgrp, tcsetpgrp 

termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow, cfmakeraw, cfgetospeed, cfgetispeed, cfsetispeed, 

cfsetospeed, tcgetpgrp, tcsetpgrp— Get and set terminal attributes, line control, get and set baud rate, get and set terminal 
foreground process group ID 

SYNOPSIS 

#include <termios.h> 

#include <unistd.h> 

int tcgetattr ( int fd, struct termios *t er mi os_ p ); 

int tcsetattr ( int f d,int optional_actions, struct termios *termios_p ); 

int tcsendbreak ( int f d,int duration ); 

int tcdrain ( int f d ); 

int tcflush ( int f d,int queue_selector ); 
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int tcflow ( int f d ,int action ); 

int cfmakeraw ( struct termios *termios_p ); 

speed_t cfgetospeed ( struct termios *termi os_p ); 

int cfsetospeed ( struct termios *t e r mi o s _ p, speed_t speed ); 

speed_t cfgetispeed ( struct termios *termi os_p ); 

int cfsetispeed ( struct termios *t e r mi o s _ p, speed_t speed ); 

pid_t tcgetpgrp ( int fd ); 

int tcsetpgrp ( int fd, pid_t pgr pi d ); 

DESCRIPTION 

Thetermios functions descri be a general terminal interface that is provided to control asynchronous communications ports 

M any of the functions described here have at er mi os.p argument that is a pointer to a termios structure. This structure 
contains the following members: 

tcflag_t c_iflag; /* input modes */ 
tcflag_t c_oflag; /* output modes */ 
tcflag_t c_cflag; /* control modes */ 
tcflag_t c_lflag;/‘localmodes*/ 
cc_t c_cc[NCCS]; /* control chars */ 

T he c_itiag flag constants are 

IGNBRK 
BRKINT 
IGNPAR 
PARMRK 

INPCK 
ISTRIP 
INLCR 
IGNCR 
ICRNL 
IUCLC 
IXON 
IXANY 
IXOFF 
IMAXBEL 

T he c_otiag flag constants are 

opost Enable implementation-defined output processing. 

olcuc M ap lowercase characters to uppercaseon output. 

onlcr M ap nl to cr-nl on output. 

ocrnl M ap cr to nl on output. 

onocr D on't output cr at column 0 . 

ONLRET D on't output CR. 

ofill Send fill characters for a delay, rather than usingatimed delay. 

ofdel Fill character is ascii del. If unset, fill character is ascii nul. 

nldly N ewline delay mask. Values are nl@ and nli . 

Carriage return delay mask. Values are crb, cRi,cR2,or cr3. 


Ignore break condition on input. 

If ignbrk is not set, generate sigint on break condition, else read break as character \c. 
Ignore framing errors and parity errors 

If ignpar is not set, prefix a character with a parity error or framing error with \377 \ 0 . 
If neither ignpar nor parmrk is set, read a character with a parity error or framing error 
as\ 0 . 

Enable input parity checking. 

Strip off eighth bit. 

Translate nl to cRon input. 

Ignore carriage return on input. 

T ranslate carriage return to newline on input (unless igncr is set). 

M ap uppercase characters to lowercase on input. 

EnablexoN/xoFF flow control on output. 

Enable any character to restart output. 

EnablexoN/xoFF flow control on input. 

Ring bell when input queue is full. 



CRDLY 



termios tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow, cfmakeraw, cfgetospeed, cfgetipeed, 

cfsetispeed, cf&oyeed, tcgetpg-p, tcsetpgrp 


TABDLY 

BSDLY 

VTDLY 

FFDLY 

T he c_cfiag flag constants are 

CSIZE 

CSTOPB 

CREAD 

PARENB 

PARODD 

HUPCL 

CLOCAL 

CIBAUD 

CRTSCTS 

Thec_itiag flag constants are 

ISIG 

I CANON 

XCASE 

ECHO 

ECHOE 

ECHOK 

ECHONL 

ECHOCTL 

ECHOPRT 

ECHOKE 

FLUSHO 

NOFLSH 

TOSTOP 

PENDIN 

IEXTEN 



H orizontal tab delay mask. Values areTABo, tabi, tab2, tab 3 , or xtabs. A value of xtabs 
expands tabs to spaces (with tab stops every eight columns). 

Backspace delay mask. V alues are bso or bsi . 

Vertical tab delay mask. Values are vto orvu. 

Form feed delay mask. Values are ffo or ffi. 

C haracter size mask. V alues are css, cso, csz.or css. 

Set two stop bits, rather than one. 

Enable receiver. 

Enable parity generation on output and parity checking for input. 

Parity for input and output is odd. 

Lower modem control lines after last process closes the device(hang up). 

Ignore modem control lines. 

M ask for input speeds (not used). 

Flow control. 

W hen any of the characters intr, quit, susp, or dsusp are received, generate the 
corresponding signal. 

Enable canonical mode. This enables the special characters eof, eol, eol2, erase, kill, 
reprint, status, and werase, and buffers by lines. 

If icanon is also set, terminal is uppercase only. Input isconverted to lowercase, except 
for characters preceded by \ . 0 n output, uppercase characters are preceded by \ and 
lowercase characters are converted to uppercase, 
echo input characters. 

If icanon is also set, the erase character erases the preceding input character, and werase 
erases the preceding word. 

If icanon is also set, the kill character erases the current line. 

If icanon is also set, echo theNL character even if echo is not set. 

If echo is also set, ascii control signals other than tab, nl, start, and stop are echoed as 
"x, where x isthe character with ASCII code 0x10 greater than the control signal. For 
example character 0x28 (bs) is echoed as ‘h. 

If icanon and iecho are also set, characters are pri nted as they are being erased. 

If icanon is also set, kill is echoed by erasing each character on the line, as specified by 
echoe and echoprt. 

Output is being flushed. Thisflag istoggled by typing the discard character. 

D i sable flushing the input and output queues when generating the sigint and sigquit 
signals, and flushing the input queuewhen generating the sigsusp signal. 

Send the sigttou signal to the process group of a background process that tri es to write 
to its controlling terminal. 

All characters in the input queue are reprinted when the next character is read, (bash 
handles typeahead thisway.) 

Enable implementation-defined input processing. 


tcgetattr 0 gets the parameters associated with the object referred by td and stores them in thetermios structure referenced 
by ter mi os. p. T his function may be invoked from a background process; however, the terminal attributes may be 
subsequently changed by a foreground process. 
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tcsetattro sets the parameters associated with the terminal (unless support is required from the underlying hardware that is 
not available) from thetermios structure referred to by t e r mi os.p. optionai_actions specifies when the changes take effect: 

tcsanow T he change occurs immediately. 

tcsadrain T he change occurs after all output written to fd has been transmitted. This function 

should be used when changing parameters that affect output. 
tcsaflush T he change occurs after all output written to the object referred by td has been 

transmitted, and all input that has been received but not read will be discarded 
before the change is made. 

tcsendbreako transmitsa continuous stream of zero-valued bits for a specific duration, if theterminal isusing asynchronous 
serial data transmission. If duration is zero, it transmits zero-valued bits for at least 0.25 seconds, and not more that 0.5 
seconds. If duration is not zero, it sends zero-valued bits for duration seconds, where n is at least 0.25, and not more than 
0.5. 

If theterminal is not using asynchronous serial data transmission, tcsendbreako returns without taking any action, 
tcdraino waits until all output written to the object referred to bytd has been transmitted. 

tcfiusho discards data written to the object referred to bytd but not transmitted, or data received but not read, depending 
On the value Of queue_selector: 

tciflush Flushes data received but not read 

tcoflush Flushes data written but not transmitted 

tcioflush Flushes both data received but not read, and data written but not transmitted 


tcfiowo suspends transmission or reception of data on the object referred to bytd, depending on the value of action: 
tcooff Suspends output 

tcoon Restarts suspended output 

tcioff Transmitsa stop character, which stopstheterminal devicefrom transmitting 

data to the system 

tcion T ransmitsa start character, which starts the terminal device transmitting data 

to the system 


The default on open of a terminal file is that neither its input nor its output is suspended. 

The baud rate functions are provided for getting and setting the values of the input and output baud rates in thetermios 
structure. The new values do not take effect until tcsetattro is successfully called. 

Setti ng the speed to bo instructs the modem to hang up. The actual bit rate corresponding to B 38400 may be altered with 

setserial(8). 

Theinput and output baud rates are stored in thetermios structure, 
cfmakeraw sets the terminal attributes as follows: 


termios_p->c_iflag &= '(IGNBRK]BRKINT|PARMRKjISTRIP 
] INLCR ] IGNCR j ICRNL [ IXON); 
termios_p->c_oflag &= "OPOST; 

termios_p->c_lflag &= "(ECHO|ECHONLJICANON|ISIG|IEXTEN); 
termios_p->c_cflag &= "(CSIZEJPARENB) ; 
termios_p->c_cflag J =CS8; 

cfgetospeedo returns the output baud rate stored in thetermios structure pointed to by termios_p. 

cfsetospeedo setstheoutput baud ratestored in thetermios structure pointed to by termios_p to speed, which must be one 
of these constants: 


B0 

B50 

B75 



tmpfile 



B110 

B134 

B150 

B200 

B300 

B600 

B1200 

B1800 

B2400 

B4800 

B9600 

B19200 

B38400 

B57600 

B115200 

B230400 

The zero baud rate, b@, is used to terminate the connection. I f b© is specified, the modem control lines shall no longer be 
asserted. N ormally, this will disconnect the line, cbaudex is a mask for the speeds beyond those defined in POSIX.1 (57600 
and above). Thus, B 57600 & cbaudex is non-zero. 

cfgetispeedo returns the input baud rate stored in theternios structure. 

cfsetispeedo sets the input baud rate stored in thetemios structured speed. If the input baud rate is set to zero, the input 
baud rate will be equal to the output baud rate. 

tcgetpgrpo returns process group ID of foreground processing group, or -1 on error. 

tcsetpgrpo sets process group ID to pgrpid. pgrpid must be the ID of a process group in the same session. 

RETURN VALUES 

cfgetispeedo returns the input baud rate stored in theternios structure, 
cfgetospeedo returns the output baud rate stored in theternios structure, 
tcgetpgrpo returns process group ID of foreground processing group, or -1 on error. 

All other functions return 


0 

-1 

SEE ALSO 

setserial(8) 


0 n success 

On failure and set er r no to indicate theerror 


Linux, 2 September 1995 


tmpfile 

tmpfiie— C reates a temporary fi le 

SYNOPSIS 

#include <stdio.h> 

FILE *tmpfile (void); 

DESCRIPTION 

Thetmptiieo function generates a unique temporary filename using the path prefix ptmpdir defined in <stdio.h>.The 
temporary file is then opened in binary read/write (w+b) mode. Thefile will be automatically deleted when itisclosed orthe 
program terminates. 
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RETURN VALUE 

Thetmptiieo function returnsastream descriptor, orNULL if a unique filename cannot be generated or the unique file 
cannot be opened. 

ERRORS 

EACCES 
EEXIST 
EMFILE 
ENFILE 
EROFS 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

mktemp(3), mkstemp(3), tmpnam(3), tempnam(3) 

GNU, 3 April 1993 


Search permission denied for directory in file's path prefix 
Unable to generate a unique filename 
Too many file descriptors in use by process 
Too many files open in system 
Read-only filesystem 


tmpnam 

tmpnam — C reates a name for a temporary fi le 

SYNOPSIS 

#include <stdio.h> 
char *tmpnam(char *s); 

DESCRIPTION 

Thetmpnamo function generates a unique temporary filenameusing the path prefix p_tmpdir defined in <stdio.h>. If the 
argument s is null, tmpnamo returns the address of an internal static area that holds thefilename which isoverwritten by 
subsequent calls to tmpnamo. If s is not null, the filename is returned ins. 

RETURN VALUE 

Thetmpnamo function returns a pointer to the unique temporary filename, orNULL if a unique name cannot be generated. 

ERRORS 

eexist Unable to generate a unique filename 

CONFORMSTO 

SVID 3, POSIX, BSD 4.3, ISO 9899 

SEE ALSO 

mktemp(3), mkstemp(3), tempnam(3), tmpfile(3) 


GNU, 3 April 1993 



toupper, tolower 



toascii 

toascii— C onverts character to ASC 11 

SYNOPSIS 

#include <ctype.h> 
int toascii (int c); 

DESCRIPTION 

toascii) ) converts c to a 7-bit unsigned char value that fits into the ASC II character set, by clearing the high-order bits. 

RETURN VALUE 

The value returned is that of the converted character. 

C0NF0RMST0 

SVID,BSD 

BUGS 

M any people will be unhappy if you use this function. This function will convert accented letters into random characters. 

SEE ALSO 

isascii(3), toupper(3), tolower(3) 

GNU, 16 September 1995 


toupper,tolower 

toupper, tolower— Convert letter to uppercase or lowercase 

SYNOPSIS 

#include <ctype.h> 
int toupper (int c); 
int tolower (int c); 

DESCRIPTION 

touppero converts the letter c to uppercase, if possible. 
toiower( > converts the letter c to lowercase, if possible. 

RETURN VALUE 

The value returned isthat of the converted letter, ore if theconversion was not possible. 

C0NF0RMST0 

ANSI C, BSD 4.3 

BUGS 

The details of what constitutes an uppercase or lowercase letter depend on the current locale. For example, the default locale 
does not know about umlauts, so no conversion is done for them. 

In some non-English locales, there are lowercase letters with no corresponding uppercase equivalent; theGerman sharpsis 
one example. 
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SEE ALSO 

isalpha(3), setlocale(3), locale(7) 


GNU, 4 April 1993 


tsearch,tfind,tdelete,twalk 

tsearch, tf ind, tdelete, twaik — M anage a bi nary tree 

SYNOPSIS 

#include <search.h> 

void *tsearch (const void *key,void **rootp, 

int (*compar )(const void *, const void *)); 

void *tfind (const void *key, const void **rootp, 

int (*c o mp a r )(const void *, const void *)); 

void *tdelete (const void *key,void**rootp, 

int (*c o mp a r )(const void *, const void *)); 

void twalk (const void *r oot ,void (*act i on ) (const void*nodep, 

const VISIT which, 

const int depth)); 

DESCRIPTION 

tsearch, tfind, twaik, and tdelete manage a binary tree. They are generalized from Knuth (6.2.2) Algorithm T. The first 
field in each nodeofthetreeisa pointer to the corresponding data item. (The calling program must store the actual data.) 
c o mp a r points to a comparison routine, which takes pointers to two items It should return an integer that is negative, zero, or 
positive, depending on whether the first item is less than, equal to, or greater than the second. 

tsearch searches the tree for an item, key points to the item to be searched for. root p points to a variable that points to the 
root of the tree. If the tree is empty, then the variable that r oot p points to should beset to null. If the item is found in the 
tree then tsearch returns a pointer to it. If it is not found, then tsearch adds it, and returns a pointer to the newly added 
item. 

tfind is like tsearch, except that if the item is not found, then tfind returns null. 
tdelete deletes an item from the tree Its arguments are the sameas for tsearch. 

twaik performs depth-first, left-to-right traversal of a binary tree, root points to the starting nodefor the traversal. Ifthat 
node is not the root, then only part of the tree will be visited, twaik cal Is the user function action each time a node is visited 
(that is, three times for an internal node, and once for a leaf), act i on, in turn, takes three arguments. The first is a pointer to 
thenode being visited. Thesecond isan integer that takes on the values preorder, postorder, and endorder depending on 
whether this is the first, second, or third visit to the internal node, or leaf if it is the single visit to a leaf node. (These symbols 
are defined in <search.h>.) The third argument is the depth of thenode, with zero being the root. 

RETURN VALUE 

tsearch returns a pointer to a matching item in thetree, or to the newly added item, or null if there was insufficient memory 
to add the item, tfind returns a pointer to the item, or null if no match is found. If there are multiple elements that match 
the key, the element returned is unspecified. 

tdelete returns a pointer to the parent of the item deleted, or null if the item was not found, 
tsearch, tfind, and tdelete also return null if root p wasNULL on entry. 

WARNINGS 

twaik takes a pointer to the root, while the other functions take a pointer to a variable that points to the root. 

twaik uses postorder to mean "after the left subtree, but before the right subtree." Some authorities would call this inorder, 
and reserve postorder to mean "after both subtrees." 



tsarch, tfind, tdelete twalk 
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tdelete frees the memory required for the node in the tree The user is responsible for freeing the memory for the 
corresponding data. 

The example program depends on the fact that twaik makes no further reference to a node after calling the user function 
with argument endorder or leaf. This works with theGN U library implementation, but is not in theSysV documentation. 

EXAMPLE 

The foil owing program inserts twelve random numbers into a binary tree, then prints the numbers in order. The numbers 
are removed from the tree and their storage freed during the traversal. 


#include <search.h> 

#include <stdlib.h> 

#include <stdio.h> 

void *root=NULL; 

void *xmalloc(unsigned n) 

{ 

void *p; 
p = malloc(n); 
if(p) return p; 

fprintf(stderr, "insufficient memory\n"); 
exit(1); 


int compare(const void *pa, const void *pb) 

{ 

if(*(int *)pa < *(int *)pb) return -1; 
if(*(int *)pa > *(int *)pb) return 1; 
return 0; 


void action(const void *nodep, const VISIT which, const int depth) 

{ 

int *datap; 

void *val; 

switch(which) 

{ 

case preorder: 
break; 

case postorder: 
datap = *(int **)nodep; 
printf("%6d\n", *datap); 
break; 

case endorder: 
datap = *(int **)nodep; 

(void)tdelete(datap, &root, compare); 

free(datap); 

break; 

case leaf: 

datap = *(int **)nodep; 

printf("%6d\n", *datap); 

val = tdelete(datap, &root, compare); 

free(datap); 

break; 

} 

return; 
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} 

int main() 

{ 

int i, *ptr; 
void *val; 

for (i = 0; i < 12; i++) 

{ 

ptr = (int *)xmalloc(sizeof(int)); 

*ptr = rand()&0xff; 

val = tsearch((void *)ptr, &root, compare); 
if(val == NULL) exit(1); 

} 

twalk(root, action); 
return 0; 

} 

C0NF0RMST0 

SVID 

SEE ALSO 

qsort(3), bsearch(3), hsearch(3), lsearch(3) 


GNU, 24 September 1995 


ttyname 

ttyname— Returns name of a terminal 

SYNOPSIS 

#include <unistd.h> 
char *ttyname ( int desc ); 


DESCRIPTION 

Returns a pointer to the path name of the terminal device that isopen on the file descriptor desc, or null on error (for 
example, if desc is not connected to aterminal). 

C0NF0RMST0 

POSIX.1 


SEE ALSO 

isatty(3), fstat(3) 


Linux, 20 April 1995 


tzset 

tzset— Initializes time conversion information 


SYNOPSIS 

#include <time.h> 
void tzset (void); 
extern char *t zname [2]; 



tZSZt 

DESCRIPTION 

Thetzseto function ini ti alizes the tz name variable from theiz environment variable. This function is automatically called 
by theother time conversion functions that depend on thetimezone. 

If the tz variable does not appear in the environment, the tz name variable is initialized with the best approximation of local 
wall clock time, as specified by thetzfiie(5)-formatfile/usr/iib/zoneinfo/iocaitime. 

If the tz variable does appear in the environment but its value is null or its value cannot be interpreted using any of the 
formats specified in the following paragraphs, Coordinated Universal Time(UTC) is used. 

T he value of tz can be one of three formats. The first format is used when there is no daylight saving time in the local time 
zone: 

std offset 

T he s t d string specifiesthenameof the time zone and must be three or more alphabetic characters. The offset string 
immediately follows std and specifies thetime value to be added to the local timeto get Coordinated Universal Time 
(UTC). The offset is positive if the local time zone is west of the Prime M eridian and negative if it is east. The hour must be 
between 0 and 24, and the minutes and seconds 0 and 59. 

The second format is used when there is daylight saving time: 
std offset dst [offset].start[/time],end[/time] 

There are no spacesin the specification. The initial std and offset specify the standard time zone, as described. Thedst 
string and offset specify the name and offset for the corresponding daylight savings time zone. If the offset is omitted, it 
defaults to one hour ahead of standard time. 

The start field specifies when Daylight Savings Time goes into effect and the end field specifies when the change is made 
back to Standard Time. These fields may have the following formats: 

jn This specifies thej ulian day with n between 1 and 365. February 29 isnever counted even in 

leap years. 

n ThisspecifiestheJ ulian day with n between 1 and 365. February 29 iscounted in leap years. 

Mm. w. d This specifies day d (0 <= d <= 6) of week w (1 <=w <=5) of month m (1 <=m <= 12). Week 

1 is the first week in which day d occurs and week 5 is the last week in which dayd occurs. 
Day 0 is a Sunday. 

The time fields specify when, in the local time currently in effect, the change to theother time occurs. If omitted, the default 
is 02 : 00 : 00 . 

The third format specifies that the time zone information should be read from a file 
: [filespec] 

If thefile specification filespec is omitted, thetimezone information is read from /usr/iib/zoneinto/iocaitime, which isin 
tztiie(5) format. If filespec isgiven, it specifies an-other tzf iie(5)-format file to read the time zone information from. If 
filespec does not begin with a/, the file specification is relative to the system time conversion information directory /usr/ 
lib/zoneinfo. 

FILES 

/usr/iib/zoneinfo System time zone directory 

/usr/iib/zoneinfo/iocaitime Local ti me zone f i le 

/usr/lib/zoneinfo/posixrules Rlllesfor PO SIX-Style TZS 

C0NF0RMST0 

SVID 3, POSIX, BSD 4.3 
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SEE ALSO 

date(l), gettimeofday(2), time(2), ctime(3), getenv(3), tzfile(5) 


BSD, 2July 1993 


none 

none— U ndocumented library functions 

SYNOPSIS 

Undocumented library functions 

DESCRIPTION 

This man page mentions those library functions that are implemented in the standard libraries but not yet documented in 
man pages. 

SOLICITATION 

If you have information about these functions please look in the source code, write a man page (using a style similar to that 
of the other Linux section 3 man pages), and send it to aeb@cwi.ni for inclusion in the next man page release. 

THE LIST 

des_setparity, dn_skipname, ecb_crypt, encrypt, endnetgrent, endrpcent, endutent, execlp, fcrypt, fp_nquery, fp_query, 
fp_resstat, getjnyaddress, getnetgrent, getnetname, getopt_long_only, getpublickey, getrpcbyname, getrpcbynumber, 
getrpcent, getrpcport, getsecretkey, getutid, getutline, h_errlist, host2netname, hostalias, inet_nsap_addr, 
inet_nsap_ntoa_init_des, innetgr, key_decryptsession, key_encryptsession, key_gendes, key_setsecret, lfind, libc_nls_init, 
lockf, lsearch, mcheck, memalign, mstats, mtrace, netname2host, netname2user, nlist, obstack_free, p_cdname, p_cdnname, 
p_class, p_fqname, p_option, p_query, p_rr, p_time, p_type, passwd2des, pmap_getmaps, pmap_getport, pmap_rmtcall, pmap_set, 
pmap_unset, putlong, putshort, pututline, rcmd, re_compile_fastmap, re_compile_pattern, re_match, re_match_2, re_rx_search, 
re_search, re_search_2, re_set_registers, re_set_syntax, registerrpc, res_send_setqhook, res_send_setrhook, rexec, 
rresvport, rtime, ruserok, ruserpass, setfileno, sethostfile, setkey, setlogmask, setnetgrent, setrpcent, setutent, 
siglongjmp, snprintf, stpcpy, svc_exit, svc_getreq, svc_getreqset, svc_register, svc_run, svc_sendreply, svcjjnregister, 
svcerr_auth, svcerr_decode, svcerr_noproc, svcerr_noprog, svcerr_progvers, svcerr_systemerr, svcerr_weakauth, 
svcfd_create, svcraw_create, svctcp_create, svcudp_bufcreate, svcudp_create, svcudp_enablecachesyscall, tdelete, tell, 
tfind, timegm, tr_break, tsearch, twalk, tzsetwall, ufc_dofinalperm, ufc_doit, user2netname, utmpname, valloc, vsnprintf, 
vsyslog, xdecrypt, xdr_accepted_reply, xdr_array, xdr_authdes_cred, xdr_authdes_verf, xdr_authunix_parms, xdr_bool, 
xdr_bytes, xdr_callhdr, xdr_callmsg, xdr_char, xdr_cryptkeyarg, xdr_cryptkeyres, xdr_datum, xdr_des_block, xdr_domainname, 
xdr_double, xdr_enum, xdr_float, xdr_free, xdr_getcredres, xdr_int, xdr_keybuf, xdr_keystatus, xdr_long, xdr_mapname, 
xdrjietnamestr, xdr_netobj, xdr_opaque, xdr_opaque_auth, xdr_passwd, xdr_peername, xdr_pmap, xdr_pmaplist, xdr_pointer, 
xdr_reference, xdr_rejected_reply, xdr_replymsg, xdr_rmtcall_args, xdr_rmtcallres, xdr_short, xdr_string, xdr_u_char, 
xdr_u_int, xdr_u_long, xdr_u_short, xdr_union, xdr_unixcred, xdr_vector, xdr_void, xdr_wrapstring, xdr_yp_buf, 
xdr_yp_inaddr, xdr_ypbind_binding, xdr_ypbind_resp, xdr_ypbind_resptype, xdr_ypbind_setdom, xdr_ypdelete_args, 
xdr_ypmaplist, xdr_ypmaplist_str, xdr_yppasswd, xdr_ypreq_key, xdr_ypreq_nokey, xdr_ypresp_all, xdr_ypresp_all_seq, 
xdr_ypresp_key_val, xdr_ypresp_maplist, xdr_ypresp_master, xdr_ypresp_order, xdr_ypresp_val, xdr_ypstat, 
xdr_ypupdate_args, xdrmen_create, xdrrec_create, xdrrec_endofrecord, xdrrec_eof, xdrrec_skiprecord, xdrstdio_create, 
xencrypt, xprt_register, xprt_unregister, yp_all, yp_bind, yp_first, yp_get_default_doinain, yp_maplist, ypjnaster, yp_match, 
yp_next, yp_order, yp_unbind, yp_update, yperr_string, ypprot_err 


Linux 1.3.15, 25 August 1995 
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usleep 

usieep— Suspends execution for interval of microseconds 

SYNOPSIS 

#include <unistd.h> 

void usleep(unsigned long usee); 


DESCRIPTION 

The usieep o function suspends execution of the calling process for usee microseconds. The sleep may be lengthened slightly 
by any system activity or by the time spent processing the call. 

C0NF0RMST0 

BSD 4.3 


SEE ALSO 

setitimer(2), getitimer(2), sleep(3), alarm(3), select(3) 


4 July 1993 


westombs 

westombs— C onverts a wide character stri ng to a multibyte character stri ng 

SYNOPSIS 

#include <stdlib.h> 

size_t westombs(char *s, const wchar_t *pwcs , size_t n); 

DESCRIPTION 

T he westombs () function converts a sequence of wide characters from the array p wc s into a sequence of multibyte characters 
and stores up to n bytes of multi byte characters in the array s. 

RETURN VALUE 

westombs o returns the number of bytes stored ins or -i if s contains an invalid wide character. 

C0NF0RMST0 

SVID 3, ISO 9899 

SEE ALSO 

mblen(3), mbtowc(3), mbstowcs(3), wctomb(3) 

GNU, 29 M arch 1993 


wctomb 

wctomb— C onverts a wide character to a multibyte character 

SYNOPSIS 


#include <stdlib.h> 

int wctomb(char *s , wchar_t wchar); 
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DESCRIPTION 

Thewctombf) function converts a wide character wchar into a multi byte character and, if sis not null, stores the multibyte 
character representation in s. 

RETURN VALUE 

wctombo returns the number of bytes in the multi byte character or -i if the wide character is not valid. 

C0NF0RMST0 

SVID 3, ISO 9899 

SEE ALSO 

mblen(3), mbstowcs(3), mbtowc(3), wcstombs(3) 

GNU, 29 March 1993 
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INTRODUCTION 

Thispart describes special files. 

FILES 

/dev/* Device files 

AUTHORS 

Look at the header of the manual page for the author(s) and copyright conditions. N ote that these can be different from page 
to page. 

Linux, 24July 1993 


charsets 

charsets— Programmer's view of character sets and internationalization 

DESCRIPTION 

Linux isan international operating system. Several of its utilities and device drivers (includi ng the console driver) support 
multilingual character sets including Latin-alphabet letters with diacritical marks, accents, ligatures, and entire non-Latin 
alphabets including G reek. Cyrillic, Arabic, and Hebrew. 

This manual page presents a programmer's-eye view of different character-set standards and how they fit together on Linux. 
Standards discussed include ASC11, ISO 8859, KOI8-R, Unicode, ISO 2022, and ISO 4873. 


ASCII 

ASCII (American Standard Code for Information) istheoriginal 7-bit character set, originally designed forAmerican 
English. It is currently described by the EC MA-6 standard. 

An ASCII variant replacing the American crosshatch/octothorp^hash pound symbol with the British pound-sterling symbol 
is used in G reat Britain; when needed, the American and British variants may be distinguished asU .S. ASCII and U .K. 
ASCII. 

As Linux was written for hardware designed in the United States, it natively supports U.S. ASCII. 


ISO 8859 

ISO 8859 is a series of 10 8-bit character sets, all of which have U.S. ASCII in their low (7-bit) half, invisible control 
characters in positions 128 to 159, and 96 fixed-width graphics in positions 160-255. 

Of these, the most important is I SO 8859-1 (Latin-1). It is natively supported in the Linux console driver, fairly well 
supported in X11R6, and isthe base character set of H TM L. 


Console support for the other 8859 character sets is avail able under Linux through user-mode utilities (such assetfont(8)) 
that modify keyboard bindings and the EGA graphics table and employ the "user mapping" font table in the console driver. 


Here are brief descriptions of each set: 


8859-1 (Latin-1) 


8859-2 (Latin-2) 

8859-3 (Latin-3) 
8859-4 (Latin-4) 


Latin-1 covers most W estern European languages such asAlbanian, Catalan, Danish, 
Dutch, English, Faroese, Finnish, French, German, Galician, Irish, Icelandic, Italian, 
N orwegian, Portuguese, Spanish, and Swedish. The lack of the ligatures D utch ij, 
French oe, and old-style German quotation marks istolerable. 

Latin-2 supports most Latin-written Slavic and Central European languages: Czech, 
German, H ungarian, Polish, Rumanian, Croatian, Slovak, and Slovene. 

Latin-3 is popular with authors of Esperanto, Galician, M altese, and Turkish. 

Latin-4 introduced letters for Estonian, Latvian, and Lithuanian. It is essentially 
obsolete; see 8859-10 (Latin-6). 
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8859-5 


8859-6 


8859-7 

8859-8 

8859-9 (Latin-5) 
8859-10 (Latin-6) 


Cyrillic letters supporting Bulgarian, Byelorussian, M acedonian, Russian, Serbian, and 
Ukrainian. Ukrainians read the letter ghe with downstrokeas/ieh and would need aghe 
with upstroke to write a correct grte. (See the discussion of KOI8-R in the next 
subsection.) 

Supports Arabic. The 8859-6 glyph table is a fixed font of separate letter forms, but a 
proper display engine should combine there pairwise into initial, medial, and final 
forma 

Supports modern G reek. 

Supports H ebrew. 

This is a variant of Latin-1 that replaces rarely used Icelandic letters with T urkish ones. 
Latin-6 adds the last Inuit (Greenlandic) and Sami (Lappish) letters that were missing in 
Latin 4 to cover the entire N ordic area. RFC 1345 listed a preliminary and different 
Latin 6. Skolt Sami still needs a few more accents than these. 


K0I8-R 

KOI8-R is a non-ISO character set popular in Russia. The lower half isU.S. ASCII; the upper is a Cyrillic character set 
somewhat better designed than ISO 8859-5. 

Console support for KO18-R is available under Linux through user-mode utilities that modify keyboard bindings and the 
EGA graphics table, and that employ the "user mapping” fonttablein the console driver. 

UNICODE 

Unicode (ISO 10646) is a standard that aims to unambiguously represent every known glyph in every human language. 
Unicode's native encoding is 32-bit (older versions used 16 bits). Information on U nicode is available at http://www. 
unicode.com. 

Linux representsU nicode using the 8-bit UnicodeT ransfer Format (UTF-8). UTF-8 is a variable length encoding of 
Unicode. It uses 1 byte to code 7 bits, 2 bytes for 11 bits, 3 bytes for 16 bits, 4 bytes for 21 bits, 5 bytes for 26 bits, and 
6 bytes for 31 bits. 

Let 0 , i, x stand for a zero, one, or arbitrary bit. A byteoxxxxxxx stands for the Unicode 00000000 oxxxxxxx, which codes the 
samesymbol asthe ASC11 @xxxxxxx. Thus, ASCII goesunchanged into UTF-8, and peopleusing only ASCII do not notice 
any change— not in code, and not in file size. 

A byte ii0xxxxx is the start of a 2-bytecode, and noxxxxx 1 oyyyyyy is assembled into 00000 XXX xxyyyyyy. A byte nioxxxx is 
the start of a 3-byte code, and nioxxxx 1 oyyyyyy iozzzzzz is assembled into xxxxyyyy yyzzzzzz. (W hen utf-8 is used to code 
the 31-bit ISO 10646, then this progression continues up to 6-bytecodes.) 

For ISO-8859-1 users this means that the characters with high bit set now are coded with two bytes. This tends to expand 
ordinary text files by one or two percent. There are no conversion problems, however, si nee the U nicode value of I SO-8859- 
1 symbols equals their I SO-8859-1 value (extended by eight leading zero bits). For Japanese users, this means that the 16-bit 
codesnow in common use will take three bytes, and extensive mapping tables are required. M any Japanese therefore prefer 
iso 2022 . 

N ote that UTF-8 is self-synchronizing: ioxxxxxx is a tail, any other byte is the head of a code. N otethat the only way ASC 11 
bytes occur in a UTF-8 stream is as themselves. In particular, there are no embedded NULSor /s that form part of some larger 
code. 

BecauseASCII, and, in particular, nul and /, are unchanged, the kernel does not notice that UTF-8 is being used. It does not 
care at all what the bytes it is handling stand for. 

Rendering of Uni code data streams is typically handled through subfont tables that map a subset of U nicode to glyphs. 
Internally, the kernel uses Unicode to describe the subfont loaded in video RAM . This means that in UTF-8 mode one can 
use a character set with 512 different symbols. This is not enough for Japanese, Chinese, and Korean, but it is enough for 
most other purposes. 
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ISO 2022 AND ISO 4873 

The ISO 2022 and 4873 standards describe a font-control model based on VT100 practice. This model is (partially) 
supported by the Linux kernel and by xterm(l). It is popular in Japan and Korea. 

There are four graphic character sets, called GO, Gl, G2, and G3, and one of them is the current character set for codes with 
high bit zero (initially GO), and one of them is the current character set for codes with high bit one (initially Gl). Each 
graphic character set has 94 or 96 characters, and is essentially a 7-bit character set. It uses codes either 040-0177 ( 041 - 0176 ) 
or 0240-0377 (0241-0376). GO always has size 94 and uses codes 041 - 0176 . 

Switching between character sets is done usi ng the shift functions "N (soori_si),“0 (si ori_s 0 ), esc n (ls 2 ), esc 0 (LS3), esc 
n (SS2), 

esc 0 (ss3), esc ' (lsir), esc } (ls 2 r), esc | (ls3r). T he function LSn makes character set Gn the current one for codes with 
high bit zero. The function LSnR makes character set Gn the current one for codes with high bit one. The function ssn makes 
character set G n (n =2 or 3) the current one for the next character only (regardless of the value of its high order bit). 

A 94-character set is designated asGn character set by an escape sequence esc ( xx(forGO), esc ) xx(forGl), esc * xx (for 
G2), esc + xx (for G3), where xx is a symbol or a pair of symbols found in the I SO 2375 International Register of Coded 
Character Sets. For example, esc ( @ selects the I SO 646 character set as GO, esc ( a selects the U.K. standard character set 
(with pound instead of number sign), esc (b selectsASCII (with dollar instead of currency sign), esc ( m selects a character 
set for African languages, esc ( < a selects the Cuban character set, and so on. 

A 96-character set is designated as Gn character set by an escape sequence esc - xx (for G1), esc . xx (for G 2) or esc / xx 
(forG3). For example, esc - Gselectsthe FI ebrew alphabet as Gl. 

A multi byte character set is designated as Gn character set by an escape sequence esc $ xx or esc $ ( xx (for G 0), esc $ ) 
xx (for Gl), esc $ * xx (for G2), esc $ + xx (for G3). For example, esc $ ( c selects the Korean character set for GO. The 
Japanese character set selected by esc $ b has a more recent version selected by esc & @esc $ b. 

ISO 4873 stipulates a narrower use of character sets, where GO is fixed (always ASCII), so that Gl, G2, and G3 can only be 
invoked for codeswith thehigh order bit set. In particular, “N and “0 are not used anymore esc ( xx can be used only with 
xx=B, and esc ) xx, esc * xx, esc + xx are equivalent to esc - xx, esc . xx, and esc / xx, respectively. 

SEE ALSO 

console(4), console_ioctl(4), console_codes(4) 

Linux, 5 November 1996 


console 

console— Consoleterminal and virtual consoles 

DESCRIPTION 

A Linux system has up to 63 virtual conso/es(character devices with major number 4 and minor number 1 to 63), usually 
called /dev/ttyn with 1 n 63. T he current console is also addressed by /dev/consoie or /dev/tty 0 , the character device with 
major number 4 and minor number 0. The device files /dev/* are usually created using the script makedev, or using mknod(l), 
usually with mode 0622 and owner root.tty. 

Beforekernel version 1.1.54, thenumber of virtual consoles was compiled into the kernel (in tty.h: #detine nr_consoles s) 
and could be changed by editing and recompiling because version 1.1.54 virtual consoles are created on-the-fly, as soon as 
they are needed. 

Common ways to start a process on a console are the following: 

■ Tell init(8) (in imttab(5)) to start a getty(8) on the console 

■ Ask open(l) to start a process on the console 

■ Start x; it will find the first unused console and display its output there. (There is also the ancient dosheii(8).) 
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Common ways to switch consoles are the following: 

■ UseAlt-tf n or Ctrl-tAlt-tfn to switch to console n; AltGr+Fn might bring you to console n+12 [here Alt and AltGr refer 
to the left and right Alt keys, respectively] 

■ U se Alt+RightArrow or Alt-HeftArrow to cyclethrough the presently allocated consoles 

■ Use the program chvt(l). (The key mapping can beset by the user; seeioadkeys(l); the preceding key combinations are 
according to the default settings.) 

The command disaiioc(8) will free the memory taken by thescreen buffers for consoles that no longer have any associated 
process. 

PROPERTIES 

C onsoles carry a lot of state. I hope to document that some other time. T he most i mportant fact is that the consoles si mulate 
vtlOO terminals. In particular, a console is reset to the initial state by printing the two characters ESC c. All escape sequences 
can be found in console codes(4). 

FILES 

/dev/console 

/dev/tty* 

SEE ALSO 

charsets(4), console_codes(4), console_ioctl(4), mknod(l), tty(4), ttys(4), getty(8), init(8), chvt(l), open(l), disalloc(8), 
loadkeys(l), resizecons(8), setfont(8), mapscrn(8) 

Linux, 31 October 1994 


console_codes 

consoie_codes— Linux console escape and control sequences 

DESCRIPTION 

T he Linux console implements a large subset of the VT102 and ECM A-48/ISO 6429/AN SI X3.64 terminal controls, plus 
certain private-mode sequences for changing the color palette, character-set mapping, and so on. In the following tabular 
descriptions, the second column gives EC M A-48 or DEC mnemonics(the latter if prefixed with D EC) for the given 
function. Sequences without a mnemonic are neither ECM A-48 nor VT 102. 

After all the normal output processing has been done, and a stream of characters arrives at the console driver for actual 
printing, the first thing that happens is a translation from the code used for processing to the code used for printing. 

If the console is in UTF-8 mode, then the incoming bytes are first assembled into 16-bit U ni code codes. Otherwise, each 
byte is transformed according to the current mapping table (which translates it to a U ni code value). (See the "Character Sets" 
subsection for discussion.) 

In the normal case, the Unicode value is converted to a font index, and this is stored in video memory, so that the corre¬ 
sponding glyph (as found in video ROM ) appears on thescreen. N ote that the use of U ni code (and the design of the PC 
hardware) allows the use of 512 different glyphs simultaneously. 

If the current Unicode value is a control character, or you are currently processing an escape sequence, thevalue will treated 
specially. Instead of being turned into a font index and rendered as a glyph, it may trigger cursor movement or other control 
functions. (See the "Li nux C onsole C ontrols” subsection.) 

It is generally not good practice to hardwire terminal controls into programs. Linux supports a terminto(5) database of 
terminal capabilities. Rather than emitting console escape sequences by hand, you will almost always want to use a 
terminfo-awarescreen library or utility such asncurses(3), tput(l), or reset(l). 
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LINUX CON SOLE CONTROLS 

This section describes all the control characters and escape sequences that invoke special functions (that is, anything other 
than writing a glyph at the current cursor location) on the Linux console 

CONTROL CHARACTERS 

A character is a control character if (before transformation according to the mapping table) it has one of the 14 codes 00 
(nul), 07 (bel), 08 (bs), 09 (ht), 0a (lf), 0b (vt), 0c (ff), 0d (cr), 0e (so), «f (si), is (can), ia (sub), ib (esc), 7f (del). 0 ne can 
set a display control characters mode (see below), and allow 07 , 09 , 0 b, is, 1 a, 7f to be displayed as glyphs. On the other 
hand, in UTF-8 mode all codes 00 - it are regarded as control characters, regardless of any display control characters mode. 

If you have a control character, it is acted upon immediately and then discarded (even in the middle of an escape sequence) 
and the escape sequence continues with the next character. (H owever, esc starts a new escape sequence, possibly aborting a 
previous unfinished one, and can and sub abort any escape sequence) The recognized control characters are bel, bs, ht, lf, 
vt, ff, cr, so, si, can, sub, esc, del, csi. They do what one would expect: 

bel (0x07, 'g) beeps. 

bs ( 0 x 08 , 'h) backspaces one column (but not past the beginning of the line). 
ht (0x09, "i) goes to the next tab stop or to the end of the line if there is no earlier tab stop. 
lf ( 0 x 0 A, “j), vt ( 0 x 0 B, "k) and ff < 0 x 0 c, "l) all givea linefeed. 
cr ( 0 x 0 D, 'm) gives a carriage return. 

so (0x0E, - n) activates the G1 character set, and if lf/nl (new line mode) is set, also a carriage return. 

si ( 0 x 0 f, "o) activates the GO character set. 

can ( 0 xi 8 , "x) and sub ( 0 x 1 a, ~ z ) interrupt escape sequences. 

esc ( 0 x 1 b, •[) starts an escape sequence. 

del (0x7f) is ignored. 

csi (0x9b) is equivalent to esc [. 

ESC SEQUENCES, NOT CSI SEQUENCES 


ESC c 

RIS 

Reset. 

ESC D 

IND 

Linefeed. 

ESC E 

NEL 

N ewline. 

ESC H 

HTS 

Set tab stop at current column. 

ESC M 

RI 

Reverse linefeed. 

ESC Z 

DECID 

DEC private identification. The kernel returns the string 
esc [ ? 6 c, claiming that it isaVT 102. 

ESC 7 

DECSC 

Save current state (cursor coordinates, attri butes, character 
sets). 

ESC 8 

DECRC 

Restore most recently saved state. 

ESC [ 

CSI 

Control sequence introducer. 

ESC % 


Start sequence selecti ng character set. 

ESC % @ 


Select default (ISO 646/ ISO 8859-1). 

ESC % G 


Select UTF-8. 

ESC % 8 


Select UTF-8 (obsolete). 

ESC # 8 

DECALN 

DEC screen alignment test: fill screen with Es. 

ESC ( 


Start sequence defining GO character set. 

ESC ( B 


Select default (ISO 8859-1 mapping). 

ESC ( 0 


Select vtlOO graphics mapping. 
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ESC ( U 


Select null mapping— straight to character ROM . 

ESC ( K 


Select user mapping, the map that is loaded by the utility 

mapscrn(8). 

ESC ) 


Start sequence defining G1 (followed by one of b, 0 , u, k, as 
above). 

ESC > 

DECPNM 

Set numeric keypad mode. 

ESC = 

DECPAM 

Set application keypad mode. 

ESC ] 

osc 

(Should be: Operating system command) esc ] p nmggbb: 
set palette, with parameter given in 7 hexadecimal digits 


after the final p H eren is the color (0-16), and rrggbb 
indicates the red/green/blue values (0-255). esc ] r: reset 
palette. 


ECMA-48 CSI SEQUENCES 

csi (or esc [) is followed by a sequence of parameters, at most npar(16), that are decimal numbers separated by semicolons. 
An empty or absent parameter is taken to be 0 . The sequence of parameters may be preceded by a single question mark. 

H owcver, after csi [ (or esc [ [) a single character is read and this entire sequence is ignored. (The idea is to ignore an 
echoed function key.) 

The action of a csi sequence is determined by its final character. 


Character Function 


D escription 


A 

B 

c 

D 

E 

F 

G 

H 

J 


ICH 

CUU 

CUD 

CUF 

CUB 

CNL 

CPL 

CHA 

CUP 

ED 


K 


EL 


L 

M 

P 

X 

a 

c 

d 

e 

f 


IL 

DL 

DCH 

ECH 

HPR 

DA 

VPA 

VPR 

HVP 


I nsert the indicated #of blankcharacters. 

M ove cursor up the indicated #of rows. 

M ove cursor down the indicated #of rows. 

M ove cursor rightthe indicated #of columns 
M ove cursor left the indicated #of columns. 

M ove cursor down theindicated #of rows, to column 1. 
M ove cursor up theindicated # of rows, to column 1. 

M ove cursor to indicated column in current row. 

M ove cursor to theindicated row, column (origin at 1,1). 
Erase display (default: from cursor to end of display). 
esc [ i j: erase from start to cursor. 
esc [ 2 j: erasewholedisplay. 

Erase line (default: from cursor to end of line). 
esc [ i k: erase from start of line to cursor. 
esc [ 2 k: erasewholeline. 

Insert theindicated #of blanklines. 

Delete the indicated #of lines. 

Delete the indicated #of characters on the current line. 
Erase the indicated #of characters on the current line. 

M ove cursor rightthe indicated #of columns 
Answer ESC [ ? 6 c: 'I am a VT102'. 

M ove cursor to the indicated row, current column. 

M ove cursor down theindicated #of rows. 

M ove cursor to the indicated row, column. 


continues 
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Character 

Function 

Description 

g 

TBC 

W ithout parameter: clear tab stop at the current position. 
esc [ 3 g: delete all tab stops. 

h 

SM 

Set mode. 

1 

RM 

Reset mode. 

m 

SGR 

Set attributes. 

n 

DSR 

Status report. 

q 

DECLL 

Set keyboard LEDs. 
esc [ 0 q: clear all LEDs 
esc [ i q: set Scroll Lock LED 
esc [ 2 q: set N urn Lock LED 
esc [ 3 q: set Caps Lock LED 

r 

DECSTBM 

Set scrolling region; parameters are top and bottom row. 

s 

? 

Save cursor location. 

u 

? 

Restore cursor location. 

■ 

HPA 

M ovecursorto indicated column in current row. 


EC MA-48 SET GRAPH ICS RENDITION 

TheECMA-48 SGR sequence esc [ <parameters> m sets display attributes. Several attributes can beset in the same 
sequence. 


Parameter 


1 

2 

4 

5 
7 
10 
11 
12 

21 

22 

24 

25 
27 

30 

31 

32 

33 

34 

35 


Result 

Reset all attributes to their defaults 
Set bold. 

Set half-bright (simulated with color on a color display). 

Set underscore (simulated with color on a color display). 

(Thecolorsused tosimulatedim orunderlinearesetusingEsc ] ....) 

Set blink. 

Set reverse video. 

Reset selected mapping, display control flag, and toggle meta flag. 

Select null mapping, set display control flag, reset toggle meta flag. 

Select null mapping, set display control flag, set toggle meta flag. (The toggle meta flag 
causes the high bit of a byte to be toggled before the mapping table translation is done.) 
Set normal intensity. (Thisisnotcompatiblewith EC MA-48.) 

Set normal intensity. 

Underline off. 

Blink off. 

Reverse video off. 

Set black foreground. 

Set red foreground. 

Set green foreground. 

Set brown foreground. 

Set blue foreground. 

Set magenta foreground. 
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Param&er 

Result 

36 

Set cyan foreground. 

37 

Set white foreground. 

38 

Set underscore on, set default foreground color. 

39 

Set underscore off, set default foreground color. 

40 

Set black background. 

41 

Set red background. 

42 

Set green background. 

43 

Set brown background. 

44 

Set blue background. 

45 

Set magenta background. 

46 

Set cyan background. 

47 

Set white background. 

49 

Set default background color. 

ECMA-48 MODE SWITCHES 

ESC [ 3 h 

deccrm (default off): D isplay control chars 

ESC [ 4 h 

decim (default off): Set insert mode. 

ESC [ 20 h 

lf/nl (default off): Automatically follow echo of lf, vt, or ff with cr. 

ECMA-48 STATUS REPORT COMMANDS 

ESC [ 5 n 

Devicestatus report (D SR): Answer is esc [ 0 n (Terminal OK). 

ESC [ 6 n 

Cursor position report (CPR): Answer is esc [ y ; x r, where x, y is the cursor 
location. 

DEC PRIVATE MO DE(DECSET/DECRST) SEQUENCES 

These are not described in ECMA-48. The Set M ode sequences are listed; the Reset M ode sequences are obtained by 
replacingthefinal h by i. 

ESC [ ? 1 h 

decckm (default off): W hen set, the cursor keys send an esc 0 prefix, rather than 

ESC [. 

ESC [ ? 3 h 

deccolm (default off =80 columns): 80/132 col mode switch. The driver sources note 


that this alone does not suffi ce; some user-mode uti lity such as resizecons(8) has to 
change the hardware registers on the console video card. 


ESC | 

; ? 5 h 

decscnm (default off): Set reverse-video mode. 

ESC | 

; ? 6 h 

decom (default off): When set, cursor addressing is relative to the upper left corner of 
the scrolling region. 

ESC | 

; ? 7 h 

DECAWM(defaulton): Set autowrap on. In this mode, a graphics character emitted after 
column 80 (or column 132 of deccolm ison) forces a wrap to the beginning of the 
following line first. 

ESC | 

: ? 8 h 

decarm (default on): Set keyboard autorepreat on. 

ESC | 

: ? 9 

h X 10 M ouse Reporting (default off): Set reporting mode to 1 (or reset to 0 ). 

(See"M ouseTracking.") 

ESC | 

; ? 25 h 

deccm (default on): M ake cursor visible 

ESC | 

: ? 1000 h 

xi 1 M ouse Reporting (default off): Set reporting mode to 2 (or reset to 0). 

(See"M ouseT racking.") 
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LINUX CONSOLE PRIVATE CSI SEQUENCES 

The following sequences are neither EC MA-48 nor native VT102. They are native to the Linux console driver. Colors are in 
SGR parameters: 0 = black, 1 = red, 2 = green, 3 = brown, 4 = blue, 5 = magenta, 6 =cyan, 7 = white. 


ESC 

1 ; n ] 

Set colorn as the underli ne color 

ESC 

2 ; n ] 

Set colorn as the dim color 

ESC 

8 ] 

M ake the current color pair the default attributes 

ESC 

9 ; n ] 

Set screen blank time-out to n minutes 

ESC 

10 ; n ] 

Set bell frequency in Hz 

ESC 

11 ; n ] 

Set bell duration in msec 

ESC 

12 1 n ] 

Bring specified consoleto thefront 

ESC 

13 ] 

Unblank the screen 

ESC 

14 ] 

Set the VESA powerdown interval 

CHARACTER SETS 



T he kernel knows about four translations of bytes i nto console-screen symbols. T he four tables are 

■ LatinltoPC 

■ VT100 graphicsto PC 

■ PC to PC 

■ User-defined 

There are two character sets, called GO and Gl, and one of them is the current character set. (Initially GO.) T yping’N causes 
G1 to become current, ‘ 0 causes G 0 to become current. 

These variables go and gi point to a translation table, and can be changed by the user. Initially, they point at the first two 
tables, Latinl to PC and VT100 graphicsto PC, respectively. Thesequences esc ( Band esc ( 0 and esc ( u and esc ( k 
cause gc to point at the first, second, third, and fourth translation tables in the preceding list, respectively. Thesequences esc 
) Band esc ) 0 and esc ) u and esc ) k cause gi to point at thefirst, second, third, and fourth translation tables in the 
preceding list, respectively. 

The sequence esc c causes a terminal reset, which is what you want if the screen is all garbled. The oft-advised "echo 'v'o'' 
will only make GO current, but there is no guarantee that gc points at the first table. In some distributions there is a program 
reset(l) that just does echo "[c. If your terminfo entry for the console is correct (and hasan entry rsi=c), then tput reset 
will also work. 

The user-defined mapping table can beset using mapscrn(8). The result of the mapping is that if a symbol c is printed, the 
symbols = map[c] is sent to the video memory. The bitmap that corresponds to s isfound in the character rom, andean be 
changed using setfont(8). 

MOUSE TRACKING 

The mouse tracking facility isintended to return xterm-cornpatible mouse status reports. Because the console driver has no 
way to know the device or type of the mouse, these reports are returned in the console input stream only when thevirtual 
terminal driver receives a mouse update ioctl. T hese ioctls must be generated by a mouse-aware user-mode application such 
asthegpm(8) daemon. 

Parameters for all mouse tracking escape sequences generated byxterm encode numeric parametersin a single character as 
vaiue+ 040 . For example, < is 1. The screen coordinate system isl-based. 

ThexiG compatibility mode sends an escape sequence on button press encodingthelocation and the mouse button pressed. 
It is enabled by sending esc [ ? 9 h and disabled with esc [ ? 9 l.Onbutton press, xterm sends esc [ m bxy (six charac¬ 
ters). H ereb is button 1, and x and y are the x and y coordinates of the mouse when the button was pressed. This is the same 
code the kernel also produces. 




console codes 



N ormal tracking mode (not implemented in Linux 2.0.24) sends an escape sequence on both button press and release. 

M odifier information is also sent. It isenabled by sending esc [ ? 1000 h and disabled with esc [ 1000 1 .0 n button press 
or release, xterm sends esc [ m bxy.Thelow two bits of b encode button information: 0 =M B1 pressed, iMM B2 pressed, 

2 MM B3 pressed, 3=release.Theupper bits encode what modifiersweredown when the button was pressed and are added 
together: 4=Shift, sMM eta, 1 6=C ontrol. Again, x and y arethex and y coordinates of the mouse event. The upper-left corner 
is (1,1). 

COMPARISONS WITH OTHER TERMINALS 

Many different terminal types are described, like theLinux console, as being VT 100-compatible. Here we discuss differences 
between theLinux console and the two most important others, the D EC VT102 and xterm(l). 

CONTROL-CHARACTER HANDLING 

Thevti 02 also recognized thefollowing control characters: 

nul ( 0 x 00 ) was ignored. 

enq (0x05) triggered an answerback message. 

dci ( 0 x 1 1 , 'q, xon) resumed transmission. 

dc3 ( 0 x 13 , "s, xoff) caused vti00 to ignore (and stop transmitting) all codes except xoff and xon. 
vti 00 -I ike dci/dc3 processing may be enabled by the tty driver. 

Thexterm program (in vti 00 mode) recognizes the control characters bel, bs, ht, lf, vt, ff, cr, so, si, esc. 

ESCAPE SEQUENCES 

T he following VT 100 console sequences are not implemented on theLinux console: 


Escape Sequence 

Function 

Desription 

ESC N 

SS2 

Single shift 2. (Select G 2 character set for the next 
character only.) 

ESC 0 

SS3 

Single shift 3. (Select G 3 character set for the next 
character only.) 

ESC P 

DCS 

Device control string (ended by esc \). 

ESC X 

SOS 

Start of string. 

ESC " 

PM 

Privacy message (ended by esc\). 

ESC \ 

ST 

String terminator. 

ESC * ... 


D esi gnate G 2 character set. 

ESC + ... 


D esi gnate G 3 character set. 


The program xterm (in vti 00 mode) recognizes esc c, esc # 8, esc >, esc =, esc d, esc e, esc h, esc m, esc n, esc 0 , esc p 
... esc esc z (it answers esc [ ? 1 ; 2 c, "I am a vtlOO with advanced video option”) and esc ' ... esc with the same 
meanings as indicated above. It accepts esc (, esc ), esc *, esc + followed by 0 , a, b for the dec special character and line 
drawing set, uk, and usascii, respectively. 11 accepts esc ] for the setting of certain resources: 


ESC ] 0 ; txt BEL 
ESC ]1 ; txt BEL 
ESC ] 2 ; txt BEL 
ESC ] 4 6 ; name BEL 
ESC ] 5 0 ; fn BEL 


Set icon name and window title to txt. 

Set icon name to txt. 

Set window title to txt. 

Change log file to name (normally disabled by a compile-time option). 
Set font to fn. 


It recognizesthefollowing with slightly modified meaning: 


ESC 7 DECSC 
ESC 8 DECRC 


Save cursor 
Restore cursor 
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It also recognizes 

ESC F 

ESC 1 

ESC m 

ESC n LS2 

ESC 0 LS3 

ESC j LS3R 

ESC g LS2R 

ESC ' LS1R 

It does not recognize esc % ... 

CSI SEQUENCES 

Thexterm program (as of xFree86 3.1.2G) does not recognize the blink or invisible-mode SGRs. Stock X11R6 versions do 
not recognize the color-setting SGRs. All otherECMA-48 csi sequences recognized by Linux are also recognized by xterm, 
and vice versa. 

Thexterm program will recognize all of the D EC Private M ode sequences listed earlier, but none of the Linux private-mode 
sequences. For discussion of xterm'sown private-mode sequences, refer to tbeXterm Control Sequences document by Edward 
M oy and Stephen Gildea, available with thex distribution. 

BUGS 

In 2.0.23, csi is broken, and nul isnot ignored inside escape sequences. 

SEE ALSO 

console(4), console_ioctl(4), charsets(4) 

Linux, 31 October 1996 


C ursor to lower-left corner of screen (if enabled by the 
hpLowerleftBugCompat resource). 

M emory lock (per H P terminals). Locks memory above the 
cursor. 

M emory unlock (per H P terminals). 

I nvoke the G 2 character set. 

I nvoke the G 3 character set. 

I nvoke the G 3 character set as gr. 

H as no visible effect in xterm. 

I nvoke the G 2 character set as gr. 

H as no visible effect in xterm. 

I nvoke the G1 character set as gr. 

H as no visible effect in xterm. 


console ioctls 

console ioctls— loctlsfor consoleterminal and virtual consoles 

DESCRIPTION 

T he following Linux-peculiar iocti() requests are supported. Each requires a third argument, assumed hereto beargp. 


WARNING 


If you use the following information, you are going to burn yourself. Ioctls are undocumented Linux internals, liable to 
be changed without warning. UsePOSIX functions. 
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KDGETLED 


KDSETLED 


KDGKBLED 


KDSKBLED 


KDGKBTYPE 

KDADDIO 

KDDELIO 

KDENABIO 

KDDISABIO 

KDSETMODE 


KDGETMODE 

KDMKTONE 


KIOCSOUND 


GIO_CMAP 
PIO CMAP 


GIO_FONT 


Get state of LEDs, argp points to a long mt. The lower three bits of *argp are set to 
the state of the LEDs, as follows: 


LED_CAP 

0X04 

caps lock LED 

LEC_NUM 

0 x02 

num lock LED 

LED SCR 

0 x01 

scroll lock LED 


Set the LEDs. The LED s are set to correspond to the lower three bits of argp. 

H owever, if a higher order bit is set, the LEDs revert to normal, displaying the state 
of the keyboard functions of caps lock, num lock, and scroll lock. 

Before 1.1.54, the LEDs just reflected the state of the corresponding keyboard flags, 
and kdgetled/kdsetled would also change the keyboard flags. Since 1.1.54 the LEDs 
can be made to display arbitrary information, but by default they display the 
keyboard flags. The following two ioctlsareused to access the keyboard flags. 

Get keyboard flags CapsLock, NumLock, ScrollLock (not lights), argp points to achar 
that is set to the flag state. The low order three bits (mask 0 x 7 ) get the current flag 
state, and the low order bits of the next nibble (mask 0 x 70 ) get the default flag state 
(since 1.1.54). 

Set keyboard flags CapsLock, NumLock, scroiiLock (not lights), argp has the desi red 
flag state. The low order three bits (mask 0 x 7 ) have the flag state, and the low order 
bitsof the next nibble (mask 0 x 70 ) have the default flag state (since 1.1.54). 

Get keyboard type. This returns the value kb 101 , defined as 0 x 02 . 

Add I/O port as valid. Equivalent to ioperm(arg,i,i). 

Delete I/O port as valid. Equivalentto ioperm(arg,i,0). 

Enablel/O to video board. Equivalentto ioperm(0x3b4, 0x3df-0x3b4+i, 1 ). 

D isable I/O to video board. Equivalent to ioperm(0x3b4, 0x3df-0x3b4+ 1 , 0 ). 

Set text/graphics mode, argp is one of these: 

KD_TEXT 0X00 

KD_GRAPHICS 0X01 

Get text/graphics mode, argp points to a long which is set to one of the above values. 
Generate tone of specified length. The lower 16 bitsof argp specify the period in 
clock cycles, and theupper 16 bits give theduration in msec. If theduration is zero, 
thesound isturned off. Control returns immediately. For example, argp = <i25«i6) 
+ 0x637 would specify the beep normally associated with actn-G. 

Start or stop sound generation. The lower 16 bitsof argp specify the period in clock 
cycles (that is, argp = 1193180/frequency), argp = 0 turns sound off. In either case, 
control returns immediately. 

Get the current default color map from kernel, argp pointsto a 48-byte array. 

(Since 1.3.3.) 

Change the default text-mode color map. argp pointsto a 48-byte array that 
contains, in order, the red, green, and blue values for the 16 available screen colors: 0 
is off, and 255 is full intensity. The default colors are in order: black, dark red, dark 
green, brown, dark blue, dark purple, dark cyan, light grey, dark grey, bright red, 
bright green, yellow, bright blue, bright purple, bright cyan, and white (Since 
1.3.3.) 

Gets 256-character screen font in expanded form, argp pointsto an 8192-byte array. 
Fai Is with error code einval if the currently loaded font is a 512-character font, or if 
the console is not in text mode. 
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GIO_FONTX 

Gets screen font and associated information, argp points to a struct consoiefontdesc 
(seepio_FONTx). On call, thecharcount field should beset to the maximum number 
of characters that would fit in the buffer pointed to by chardata. 0 n return, the 
charcount and charheight are filled with the respective data for the currently loaded 
font, and the chardata array contains the font data if the initial value of charcount 
indicated enough space was available; otherwise the buffer isuntouched and errno is 
set to enomem. (Since 1.3.1.) 

PIO_FONT 

Sets 256-character screen font. Load font into the EGA/VGA character generator, 
argp points to a 8192-byte map, with 32 bytes per character. Only first n of them are 
used for an 8 xn font (0 < n <= 32).Thiscall also invalidates the U nicode mapping. 

PIO_FONTX 

Sets screen font and associated rendering information, argp points to a 

struct consoiefontdesc { 

u_short charcount; /* characters in font 

(256 or 512) */ 
u_short charheight; /* scan lines per 

character (1-32) */ 
char *chardata; /* font data in 

expanded form */ 

}; 

If necessary, the screen will be appropriately resized, and sigwinch sent to the 
appropriate processes. Thiscall also invalidates theUnicode mapping. (Since 1.3.1.) 

PIO_FONTRESET 

Resets the screen font, size, and Unicode mapping to the bootup defaults, argp is 
unused, but should be set to null to ensure compatibility with future versions of 
Linux. (Since 1.3.28.) 

GIO_SCRNMAP 

Get screen mapping from kernel, argp points to an area of size e_tabsz, which is 
loaded with the font positions used to display each character. Thiscall is likely to 
return useless information if the currently loaded font is more than 256 characters. 

GIO_UNISCRNMAP 

Get full Unicode screen mappingfrom kernel, argp points to an area of size 
E_TABsz*sizeof (unsigned short), which isloaded with theU nicodes each character 
represent. A special set of Unicodes, starting at u+fogb, areused to represent "direct 
to font" mappings. (Since 1.3.1.) 

PIO_SCRNMAP 

Loads the user-definable (fourth) table in the kernel that maps bytes i nto console 
screen symbols, argp points to an area of sizeE_TABsz. 

PIO_UNISCRNMAP 

Loads the user-definable (fourth) table in the kernel that maps bytes into Unicodes, 
which are then translated into screen symbols according to the currently loaded 
Unicode-to-font map. Special Unicodes starting at U+F 000 can be used to map 
directly to the font symbols. (Since 1.3.1.) 

GIO_UNIMAP 

Get U nicode-to-font mappingfrom kernel, argp points to a 
struct unimapdesc { 
u_short entry_ct; 
struct unipair 'entries; 

}; 

where entries points to an array of 
struct unipair { 
u_short Unicode; 
u_short fontpos; 

}; 

(Since 1.1.92.) 

PIO_UNIMAP 

Put U nicode-to-font mapping in kernel, argp points to a struct unimapdesc. 

(Si nee 1.1.92.) 
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PIO UNIMAPCLR 


KDGKBMODE 


KDSKBMODE 

KDGKBMETA 


KDSKBMETA 

KDGKBENT 


KDSKBENT 

KDGKBSENT 


Clear table, possibly advise hash algorithm, argp pointsto a 
struct unimapinit { 

u short advised hashsize; /* 0 if no opinion */ 

u short advised hashstep; /* 0 if no opinion */ 

u short advised hashlevel; /* 0 if no opinion */ 

}; 

(Since 1.1.92.) 

G ets current keyboard mode, argp pointsto a long, which is set to one of these: 

K_RAW 0X00 

K_XLATE 0X01 

K_MEDIUMRAW 0X02 

KJJNICODE 0X03 

Sets current keyboard mode, argp is a long equal to one of the above values. 
Getsmeta key handling mode, argp pointsto a long which is set to one of these: 
k_metabit 0x03 Set high order bit 

k_escprefix 0x04 Escape prefix 

Setsmeta key handling mode, argp is a long equal to one of the preceding values. 

Gets one entry in key translation table (keycode to action code), argp pointsto a 

struct kbentry { 

u_char kb_table; 

u_char kb_index; 

u_short kb_value; 

}; 

with the first two members filled in: kb_tabie selects the key table (0 <= kb_tabie 

<MAX_NR_KEYMAPS), and kb_index isthe keyCOde (0 <= kb index <NR_KEYS). kb_value is 

set to the corresponding action code, or k_hole if there is no such key, or k_nosuchmap 
if kb_table isinvalid. 

Setsoneentry in translation table, argp pointsto astruct kbentry. 

Gets one function key string, argp pointsto a 
struct kbsentry { 
u_char kb_func; 
u_char kb_string[512]; 


KDSKBSENT 

KDGKBDIACR 


KDGETKEYCODE 


KDSETKEYCODE 


kb_string isset to the (Nun-terminated) string corresponding to thekb_functh 
function key action code. 

Sets one function key string entry, argp pointsto astruct kbsentry. 

Read kernel accent table, argp pointsto a 

struct kbdiacrs { 

unsigned int kb_cnt; 

struct kbdiacr kbdiacr[256]; 

}; 

where kb_cnt isthe number of entries in the array, each of which isa 
struct kbdiacr {u_char diacr, base, result;}; 

Read kernel keycode table entry (scan code to keycode). argp pointsto a 

struct kbkeycode {unsigned int scancode, keycode;}; 

keycode is Set to Correspond to the given scancode.(89<=scancode <= 255 only. 

For 1 <= scancode <= 88, keycode==scancode.) (Since 1.1.63.) 

Write kernel keycode table entry, argp pointsto struct kbkeycode. (Since 1.1.63.) 
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KDSIGACCEPT 


VT_OPENQRY 
VT GETMODE 


VT_SETMODE 
VT GETSTATE 


VT_RELDISP 
VT_ACTIVATE 
VT_WAITACTIVE 
VT_DISALLOCATE 
VT RESIZE 


VT RESIZEX 


The calling process indicates its willingness to accept the signal argp when it is 
generated by pressing an appropriate key combination, (i <= argp <=nsig). 

(See spawn_console() in linux/drivers/char/keyboard.c.) 

Returns the first available (nonopened) console argp points to an int that is set to 
the number of the vt (i <= *argp <=max_nr_consoles). 

Get mode of active vt. argp points to a 
struct vt mode { 
char mode;/*vtmode*/ 

char waitv; /* if set, hang on writes if not active */ 
short relsig; /* signal to raise on release req */ 
short acqsig; /* signal to raise on acquisition */ 
short frsig; /* unused (set to 0) */ 

}; 

mode is set to oneof these values: 
vt_auto Auto vt switching 

vt_process Process controls switching 

vt_ackacq Acknowledge switch 

Set mode Of active vt. argp points to a struct vt_mode. 

Get global vt state info, argp points to a 
struct vt_stat { 

ushort v_active; /* active vt */ 
ushort v_signal;/*signalto send*/ 
ushort v_state;/*vtbitmask*/ 

}; 

For each vt in use, the corresponding bit in the v state member is set. (Kernels 1.0 
through 1.1.92.) 

Release a display. 

Switch to vt argp (l <= argp <=MAX_NR_C0NS0LES). 

W ait until vt argp has been activated. 

Deallocate the memory associated with vt argp. (Since 1.1.54.) 

Set the kernel's idea of screensize. argp points to a 

struct vt_sizes { 

ushort v_rows;/*#rows*/ 

ushort v_cols;/*#columns */ 

ushort v_scrollsize; /* no longer used */ 

}; 

Note that this does not change the video mode. Seeresizecons(8). (Since 1.1.54.) 

Set the kernel's idea of various screen parameters, argp points to a 

struct vtconsize { 

ushort v_rows; /* number of rows*/ 

ushort v cols: /* number of columns*/ 

ushort v vlin; /* number of pixel rows on screen */ 

ushort v_din; /* number of pixel rows per character */ 

ushort v vcol; /* number of pixel columns on screen */ 

ushort v ccol; /* number of pixel columns per character */ 

}; 

Any parameter may beset to zero, indicating no change, but if multiple parameters 
are set, they must be self-consistent. N otethatthisdoes not change the video mode. 
See resizecons(8). (Since 1.3.3.) 
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The action of the following ioctls depends on the first byte in the struct pointed to by argp, referred to here as the subcode. 
These are legal only for the superuser or the owner of the current tty. 


TIOCLINUX, subcode=0 

TIOCLINUX, subcode=1 
TIOCLINUX, subcode=2 


TIOCLINUX, subcode=3 
TIOCLINUX, subcode=4 
TIOCLINUX, subcode=5 

TIOCLINUX, subcode=6 

TIOCLINUX, subcode=7 

TIOCLINUX, subcode=8 


TIOCLINUX, subcode=9 


TIOCLINUX, subcode=10 


Dump the screen. Disappeared in 1.1.92. (With kernel 1.1.92 or later, read from 
/dev/vcsN or /dev/vcsaN instead.) 

Get task information. D isappeared in 1.1.92. 

Set selection, argp points to a 

struct{fchar subcode; short xs, ys, xe, ye; short sel_mode;} 

xs and ys are the starting column and row. xe and ye are the ending column and 
row. (U pper-left corner isrow=coiumn=i.) sei_mode is 0 for character-by-character 
selection, i for word-by-word selection, or 2 for line-by-line selection. The indicated 
screen characters are highlighted and saved in the static array sel buffer in devices/ 
char/console.c. 

Paste selection. The characters in the selection buffer are written tofd. 

Unblank thescreen. 

Sets contents of a 256-bit look up table defining characters in a "word", for word- 
by-word selection. (Since 1.1.32.) 

argp points to a char that is set to the value of the kernel variable shift state. (Since 
1.1.32.) 

argp points to a char that is set to the value of the kernel variable report mouse. 
(Since 1.1.33.) 

Dump screen width and height, cursor position, and all the character-attribute pairs. 
(Kernels 1.1.67 through 1.1.91 only. With kernel 1.1.92 or later, read from /dev/ 
vcsa* instead.) 

Restore screen width and height, cursor position, and all the character-attribute 
pairs. (Kernels 1.1.67 through 1.1.91 only. W ith kernel 1.1.92 or later, write to 
/dev/vcsa* instead.) 

H andlesthe power saving feature of the new generation of monitors. VESA screen 
blanking mode is set to argp[l], which governswhat screen blanking does: 

0 Screen blanking is disabled. 

1 The current video adapter register setti ngs are saved, then the 
controller isprogrammed to turn off the vertical synchronization 
pulses. This puts the monitor into standby mode. If your monitor has 
an Off_M ode timer, then it will eventually power down by itself. 

2 Thecurrent settings are saved, then both the vertical and horizontal 
synchronization pulses are turned off. This puts the monitor into off 
mode. If your monitor has no Off_M ode timer, or if you want your 
monitor to power down immediately when the blank timer times out, 
then you choose this option. (Caution: Powering down frequently 
will damage the monitor.) (Si nee 1.1.76.) 


RETURN VALUES 

-i for error, and errno is set. 


ERRORS 

errno may take on these values: 

ebadf File descriptor is invalid. 

File descriptor is not associated with acharacter special device, or the specified 
request does not apply to it. 


ENOTTY 



EINVAL 


File descriptor or argp isinvalid. 
eperm Permission violation. 


WARNING 


Do not regard this man page as documentation of the Linux console ioctls. This is provided for the curious only, as an 
alternative to reading the source. Ioctls are undocumented Linux internals, liableto be changed without warning. (And 
indeed, this page more or I ess describes the situation as of kernel version 1.1.94; there are many minor and not-so-minor 
differences with earlier versions.) 

Very often, ioctls are introduced for communication brtween the kernel and one particular well-known program (fdisk, 
hdparm, setseriai, tuneip, loadkeys, selection, settont, and so on), and their behavior will bechanged when required by 
this particular program. 

Programs using these ioctls will not be portable to other versions of U NIX, will not work on older versions of Linux, and 
will not work on future versions of Linux. 

UsePOSIX functions 


SEE ALSO 

kbd_mode(l), loadkeys(l), dumpkeys(l), mknod(l), setleds(l), setmetamode(l), ioperm(2), termios(2), execve(2), fcntl(2), 
charsets(4), console(4), console_codes(4), mt(4), sd(4), tty(4), ttys(4), vcs(4), vcsa(4), mapscrn(8), setfont(8), resizecons(8), 
/usr/include/linux/kd.h, /usr/include/linux/vt.h. 

Linux , 18 September 1995 


fd 

td— Floppy disk device 

CONFIGURATION 

Floppy drives are block devices with major number 2. Typically, they are owned by root, floppy (that is, user root, group 
floppy) and have either mode 0660 (access checking via group membership) or mode 0666 (everybody has access). The minor 
numbers encode the device type, drive number, and controller number. For each device type (that is, combination of density 
and track count), there is a base minor number. T 0 this base number, add the drive's number on its controller and 128 if the 
driveison the secondary controller. In the following device tables, n represents the drive number. 


WARNING 


If you use formats with more tracks than supported by your drive, you may cause it mechanical damage. T rying once if 
more tracks than the usual 40/80 are supported should not damage it, but no warranty is given for that. D on't create 
device entries for those formats to prevent their usage if you are not sure. 








Drive-independent device files that automatically detect the media format and capacity are 


Name Base minor# 

fdn 0 

5.25-inch double density device files: 


Name 

Capac. 

Cyl. 

Sect. 

Heads 

B as minor # 

fdnd360 

360K 

40 

9 

2 

4 

5.25-inch high density device files: 





Name 

Capac. 

Cyl. 

Sect. 

Heads 

Ba& minor # 

fdnh360 

360K 

40 

9 

2 

20 

fdnh410 

410K 

41 

10 

2 

48 

fdnh420 

420K 

42 

10 

2 

64 

fdnh720 

720K 

80 

9 

2 

24 

fdnh880 

880K 

80 

11 

2 

80 

fdnh1200 

1200K 

80 

15 

2 

8 

fdnh1440 

1440K 

80 

18 

2 

40 

fdnh1476 

1476K 

82 

18 

2 

56 

fdnh1494 

1494K 

83 

18 

2 

72 

fdnh1600 

1600K 

80 

20 

2 

92 

3.5-inch double density device files: 





Name 

Capac. 

Cyl. 

Sect. 

Heads 

Base minor # 

fdnD360 

360K 

80 

9 

1 

12 

fdnD720 

720K 

80 

9 

2 

16 

fdnD800 

800K 

80 

10 

2 

120 

fdnD1040 

1040K 

80 

13 

2 

84 

fdnDI120 

1120K 

80 

14 

2 

88 

3.5-inch high density device files: 





Name 

Capac. 

Cyl. 

Sect. 

Heads 

Base minor # 

fdnH360 

360K 

40 

9 

2 

12 

fdnH720 

720K 

80 

9 

2 

16 

fdnH820 

820K 

82 

10 

2 

52 

fdnH830 

830K 

83 

10 

2 

68 

fdnH1440 

1440K 

80 

18 

2 

28 

fdnH1600 

1600K 

80 

20 

2 

124 

fdnH1680 

1680K 

80 

21 

2 

44 

fdnH1722 

1722K 

82 

21 

2 

60 

fdnH1743 

1743K 

83 

21 

2 

76 

fdnH1760 

1760K 

80 

22 

2 

96 

fdnH1840 

1840K 

80 

23 

2 

116 

fdnH1920 

1920K 

80 

24 

2 

100 
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3.5-inch extra density device files: 


Name Capac. Cyl. Sect. Heads Baseminor# 


fdnE2880 

2880K 

80 

36 

2 

32 

fdnCompaQ 

2880K 

80 

36 

2 

36 

fdnE3200 

3200K 

80 

40 

2 

104 

fdnE3520 

3520K 

80 

44 

2 

108 

fdnE3840 

3840K 

80 

48 

2 

112 


DESCRIPTION 

td special files access the floppy disk drives in raw mode. The following iocti(2) cal Is are supported by td devices: 
fdclrprm clears the media information of a drive (geometry of disk in drive). 

fdsetprm sets the media information of a drive. The media information will be lost when the media is changed. 

fddefprm sets the media i nformati on of a drive (geometry of disk in drive). The media information will not be lost when the 

media ischanged. Thiswill disable autodetection. In order to re-enable autodetection, you have to issuean fdclrprm. 

fdgetdrvtvp displays the type of a drive (name parameter). For formats that work in several drive types, fdgetdrvtyp returnsa 

namethat is appropriate for the oldest drive type that supports thisformat. 

fdflush invalidates the buffer cachefor thegiven drive. 

fdflush invalidates the buffer cachefor thegiven drive. 

fdsetmaxerrs sets the error thresholds for reporting errors, aborting the operation, recalibrating, resetting, and reading sector 
by sector. 

fdsetmaxerrs gets the current error thresholds 
fdgetdrvtyp gets the internal name of the drive. 
fdwerrorclr clears the write error statistics 

fdwerrorget reads thewrite error statistics. Theseincludethetotal number of write errors the location and disk of the first 
write error, and the location and disk of the last write error. D isks are identified by a generation number that is incremented 
at (almost) each disk change. 

fdtwaddle switches the drive motor off for a few microseconds. This might be needed in order to access a disk whose sectors 

are too close together. 

fdsetdrvprm sets various drive parameters. 

fdgetdrvprm reads these parameters back. 

fdgetdrvstat gets the cached drive state (disk changed, write protected et al.) 

fdpolldrvstat pollsthe drive and return its state. 

fdgetfdcstat gets thefIoppy controller state. 

fdreset resets the floppy controller under certain conditions. 

fdrawcmd sendsa raw command to the floppy controller. 

For more precise information, consult also the<iinux/fd.h> and <linux/fdreg.h>include files, as well as the manual page for 
floppy control. 

NOTES 

The various formats allow you to read and write many types of disks. FI owever, if a floppy is formatted with a too small 
intersector gap, performance may drop, up to needing a few seconds to access an entire track. T o prevent this, use interleaved 
formats. It is not possible to read floppies that are formatted using GCR (group code recording), which is used by Apple II 
and M acintosh computers (800K disks). Reading floppies that are hard sectored (one hole per sector, with the index hole 
being a little skewed) isnot supported. This used to be common with older 8-inch floppies. 
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FILES 

/dev/fd* 

AUTHORS 

Alain Knaff (Alain.Knaff?imag.fr), David Niemi (niemidc@clark.net), Bill Broadhurst(bbroad?netcom.coin). 

SEE ALSO 

floppycontrol(l), mknod(l), chown(l), getfdprm(l), superformat(l), mount(8), setfd-prm(8) 

Linux, 29January 1995 


hd 

hd-M FM /ID E hard disk device 

DESCRIPTION 

hd* are block devices to access M FM/ID E hard disk drives in raw mode. The master drive on the primary ID E controller 
(major device number 3) is hda; the slave drive is hdb. T he master drive of the second controller (major device number 22) is 
hdc and the slave hdd. 

General IDE block device names have the form hdx, or hdxp, where x is a letter denoting the physical drive, and p is a 
number denoting the partition on that physical drive. The first form, hdx, is used to address the whole drive. Partition 
numbers are assigned in the order the partitions are discovered, and only nonempty, nonextended partitions get a number. 

H owever, partition numbers 1-4 are given to the four partitions described in the M B R (the primary partitions), regardless of 
whether they are unused or extended. Thus, the first logical partition will behdxs. Both DOS-type partitioning and BSD - 
disk label partitioning are supported. You can have at most 63 partitions on an ID E disk. 

For example, /dev/hda refers to all of the first ID E drive in the system; and /dev/hdb3 refers to the third DOS primary 
partition on the second one. 

They are typically created by the following: 

mknod -m 660 /dev/hda b 3 0 
mknod -m 660 /dev/hdal b 3 1 
mknod -m 660 /dev/hda2 b 3 2 

mknod -m 660 /dev/hda8 b 3 8 
mknod -m 660 /dev/hdb b 3 64 
mknod -m 660 /dev/hdbl b 3 65 
mknod -m 660 /dev/hdb2 b 3 66 


mknod -m 660 /dev/hdb8 b 3 72 
chown root.disk /dev/hd* 

FILES 

/dev/hd* 

SEE ALSO 

mknod(l), chown(l), mount(8), sd(4) 


Linux , 17 December 1992 
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ispell 

ispeii— Format of ispeii dictionaries and affix files 

DESCRIPTION 

ispeii(l) requires two files to define the language that it is spell checking. The first file is a dictionary containing words for 
the language, and the second is an affix file that defines he meaning of special flags in the dictionary. The two files are 
combined by buiidhash (see speiif 1 )) and written to a hash filethat isnot described here. 

A raw ispeii dictionary (either the main dictionary or your own personal dictionary) contains a list of words, one per line. 
Each word may optionally be followed by a slash (/) and one or more flags, which modify the root word as explained later. 
Depending on the options with which ispeii was built, case may or may not be significant in either the root word or the 
flags, independently. Specifically, if the compile-time option capitalization is defined, case is significant in therootword; if 
not, caseisignored in therootword. If the compile-time option maskbits is set to avalueof32, caseisignored in theflags; 
otherwise, case is significant in theflags. Contact your system administrator or ispeii maintainer for more information (or 
use the -w flag to find out). The dictionary should be sorted with the-f flag of sort(l) before the hash file is built; this is 
done automatically by unchiist(l), which is the normal way of building dictionaries. 

If the dictionary contains words that havestring characters (see the affix file documentation, following), they must be 
written in the format given by thedefstringtype statement in the affix file This will be the case for most non-English 
languages. Be careful to usethisformat, rather than that of your favorite formatter, when adding words to a dictionary. If 
you add words to your personal dictionary during an ispeii session, they will automatically be converted to the correct 
format. Thisfeature can be used to convert an entire dictionary if necessary: 

echo qqqqq > dummy.diet 

buiidhash dummy.diet affix-file dummy.hash 

awk 'fprint "*"gENDfprint "#"g' old-dict-file \ 

! ispell -a -T old-dict-string-type \ 

-d ./dummy.hash -p ./new-dict-file \ 

> /dev/null 
rm dummy.* 

The case of therootword controls the case of words accepted by ispeii, as follows: 

1. If therootword appears only in lowercase (for example, bob), it will be accepted in lowercase, capitalized, or all capitals. 

2. If therootword appears capitalized (for example, Robert), itwill not be accepted in all lowercase, but will be accepted 
capitalized or all in capitals. 

3. If therootword appears all in capitals (for example, U NIX), itwill only be accepted all in capitals. 

4. If therootword appears with a "funny” capitalization (for example, ITCorp), a word will be accepted only if it follows 
that capitalization, or if it appears all in capitals. 

5. M ore than one capitalization of a root word may appear in the dictionary. Flags from different capitalizations are 
combined using or. 

Redundant capitalizations (for example, bob and Bob) will be combined by buiidhash and by ispeii (for personal dictionar¬ 
ies), and can be removed from a raw dictionary by munchiist. 

For example, the dictionary 
bob 

Robert 

UNIX 

ITcorp 

ITCorp 


will accept bob, Bob, bob, Robert, Robert, unix, ITcorp, ITcorp, and itcorp, and will reject all others. Some of the unacceptable 
forms are bob, robert, Unix, and ItCorp. 
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As mentioned, root words in any dictionary may be extended by flags. Each flag is a single alphabetic character, which 
represents a prefix or suffix that may be added to the root to form anew word. For example, in an English dictionary the d 
flag can be added to bathe to make bathed. Because flags are represented as a single bit in the hashed dictionary, this results 
in significant space savings. The munchiist script will reduce an existing raw dictionary by adding flags when possible. 

When a word is extended with an affix, the affix will be accepted only if it appears in the same case as the initial (prefix) or 
final (suffix) letter of the word. Thus, for example, the entry unix/m in the main dictionary (M means add an apostrophe and 
an sto make a possessive) would accept UN IX 'S but would rqect U NIX's If U NIX'sis legal, it must appear as a separate 
dictionary entry, and it will not be combined by munchiist. (In general, you don't need to worry about these things; 
munchiist guarantees that its output dictionary will accept the same set of words as its input, so all you have to do is add 
words to the dictionary and occasionally run munchiist to reduce its size.) 

As mentioned, the affix definition file describes the affixes associated with particular flags. It also describes the character set 
used by the language. 

Although the affix-definition grammar is designed for a line-oriented layout, it is actually a free-format grammar and can be 
laid out weirdly if you want. Comments are started by a pound (sharp) sign (#), and continue to the end of the line. 
Backslashes are supported in the usual fashion (\nnn, plus specials \n, \r, \t, \v, \f, \b, and the new hex format \xnn). Any 
character with special meaning to the parser can be changed to an uninterpreted token by backslashing it; for example, you 
can declare a flag named asterisk or colon with flag n* : or flag n ::. 

The grammar will be presented in a top-down fashion, with discussion of each element. An affix-definition file must contain 
exactly one table 

tabl e : [ h e a d e r s ] [prefi xes ][suffi xes ] 

At least one of prefixes and suffixes is required. They can appear in either order. 

headers : [opti ons ] char - set s 

The headers describe options global to this dictionary and language. These include the character sets to be used and the 
formatter, and the defaults for certain ispell flags. 

options : { f mt r - s t mt [ o p t - s t mt [ f I a g - s t mt j n u m- s t mt } 

The options statements define the defaults for certain ispeii flags and for the character sets used by the formatters. 

f mt r - s t mt : { n r o f f - s t mt | t e x - s t mt } 

A fmtr-stmt statement describes characters that have special meaning to a formatter. N ormally, this statement is not 
necessary, but some languages may have preempted the usual defaults for use as language-specific characters. In this case, 
these statements may beused to redefine the special characters expected by the formatter, 
nr off-stmt : { nroffchars ] troffchars } string 

T he nrotf chars statement allows redefinition of certain nrotf control characters. The string given must be exactly five 
characters long, and must list substitutions for the left and right parentheses, the period, the backslash, and the asterisk. (The 
right parenthesis is not currently used, but is included for completeness.) For example, the statement: 
nroffchars {}. \ \* 

would replace the left and right parentheses with left and right curly braces for purposes of parsing nroff/troff strings, with 
no effect on the others (admittedly a contrived example). N otethat the backslash is escaped with a backslash, 
t ex-stmt : { TeXchars | texchars } string 

T he Texchars statement allows redefinition of certain T eX/LaTeX control characters. The string given must be exactly 
thirteen characters long, and must list substitutions for the left and right parentheses, the left and right square brackets, the 
left and right curly braces, the left and right angle brackets, the backslash, the dollar sign, the asterisk, the period or dot, and 
the percent sign. For example the statement: 


texchars ()\[]<\><\>\\$*-% 
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would replace the functions of the left and right curly braces with the left and right angle brackets for purposes of parsing 
TeX/LaT eX constructs, while retaining their functionsfor thetib bibliographic preprocessor. N ote that the backslash, the 
left square bracket, and the right angle bracket must be escaped with a backslash. 

o p t - s t mt : { c mp n d - s t mt j a f f - s t mt } 
cmpnd-stmt : compoundwords compound-opt 
aff-stmt : allaffixes on-or-off 
on-or - of f : { on j off } 

compound-opt : { on-or-off | controlled character } 

An opt-stmt, used in the preceding code, controls certain ispeii defaults that are best made language-specific. The 
aiiaffixes statement controls the default for the-p and -m options to ispeii. If aiiaffixes is turned off (the default), ispeii 
will default to the behavior of the -p flag: root/affix suggestions will only be made if there are no "near misses." If aiiaffixes 
isturned on, ispeii will default to the behavior of the -m flag: rooty affix suggestions will always be made. 

The compoundwords statement controls the default for the -b and -c options to ispeii. If compoundwords isturned off (the 
default), ispeii will default to the behavior of the-B flag: run-together words will be reported as errors. If compoundwords is 
turned on, ispeii will default to the behavior of the-c flag: run-together words will be considered as compounds if both are 
in the dictionary. This is useful for languages such as German and N orwegian, which form large numbers of compound 
words. Finally, if compoundwords is set to controlled, only words marked with the flag indicated by character (which should 
not be otherwise used) will be allowed to participate in compound formation. Because this option requires the flags to be 
specified in the dictionary, it is not available from the command line, 
flag-stmt : flagmarker character 

T he flagmarker statement describes the character that is used to separate affix flags from the root word in a raw dictionary 
file. This must be a character that is not found in any word (including in string characters; see following). The default is/ 
because this character is not normally used to represent special characters in any language, 
n um- stmt : compoundmin di gi t 

Thecompoundmin statement controls the length of the two components of a compound word. This only has an effect if 
compoundwords is turned on or if the-C flag is given to ispeii. In that case, only words at least as long as the given minimum 
will be accepted as components of a compound. The default is 3 characters. 

c h a r - s e t s : norm-sets [ a 11 - s e t s ] 

The character-set section describes the characters that can be part of a word, and defines their collating order. There must 
always be a defi nition of "normal" character sets; in addition, there may be oneor more partial definitions of "alternate" sets 
that are used with varioustext formatters, 
norm-sets : [def type ] charset-group 

A "normal" character set may optionally begin with a definition of the file suffixes that make use of this set. Following this 
are one or more character-set declarations, 
deftype : defstringtype name deformatter suffix* 

T he defstringtype declaration gives a list of file suffixes that should make use of the default stri ng characters defined as part of 
the base character set; it is only necessary if string characters are being defined. The name parameter is a string giving the 
unique name associated with these suffixes; often it is a formatter name. If the formatter is a member of thetroff family, 
nroft should be used for the name associated with the most popular macro package; members of theT eX family should use 
tex. Other names may be chosen freely, but they should be kept simple, as they are used in ispeii's-T switch to specify a 
formatter type. The deformatter parameter specifies the deformatting style to use when processing files with the given 
suffixes. Currently, thismust be either tex or nroft. The suffix parameters are a whitespace-separated list of strings which, if 
present at the end of a filename indicate that the associated set of string characters should be used by default for this file. For 
example, the suffix list for the trotf family typically includes suffixes such as .ms, .me, .mm, and so on. 
charset-group : { char-stmt j string-stmt | dup-stmt}* 



A char-stmt describes single characters; a string-stmt describes characters that must appear together as a string, and which 
usually represent a single character in the target language. Either may also describe conversion between uppercase and 
lowercase. A dup-stmt is used to describe alternate forms of string characters, so that a single dictionary may be used with 
several formatting programs that use different conventions for representing non-ASCII characters. 

char-stmt : wordchars char act er - r ange 

| wordchars I owercase-range uppercase-range 
| boundarychars character-range 

| boundarychars Iowercase-range upper case-range 

string-stmt : stringchar st r i ng 

| stringchar I owercase-stri ng uppercase-stri ng 

Characters described with the boundarychars statement are considered part of a word only if they appear singly, embedded 
between characters declared with thewordchars or stringchar statements. For example if the hyphen is a boundary character 
(useful in French), the string too-bar would be a single word, but -too would be the same as too, and too-bar would be two 
words separated by nonword characters. 

If two ranges or strings are given in a char-stmt or string-stmt, the first describes characters that are interpreted as lowercase 
and thesecond describes uppercase. In the case of a stringchar statement, thetwo stringsmust be of the same length. Also, 
in a stringchar statement, theactual strings may contain both uppercase and characters themselves without difficulty; for 
instance, the statement: 

stringchar "\\*(sS" "\\*(Ss" 

is legal and will not interfere with (or be interfered with by) other declarations of 11 s 11 and “S" as lowercase and uppercase, 
respectively. 

A final note on string characters: so me languages col I ate certain special characters as if they were strings. For example the 
German "a-umlaut” is traditionally sorted as if it were ae. ispeii is not capable of this; each character must be treated as an 
individual entity. So in certain cases, ispeii will sort a list of words into a different order than the standard "dictionary" 
order for the target language. 

a 11 ■ s e t s : a 111 y p e [ a 11 - s t mt *] 

Because different formatters use different notations to represent non-ASCII characters, ispeii must be aware of the represen¬ 
tations used by these formatters. T hese are declared as alternate sets of string characters. 

alttype : altstringtype name suffix* 

T he aitstringtype statement introduces each set by declaring the associated formatter name and filename suffix list. This 
nameand list are interpreted exactly as in thedetstringtype statement. Following this header are one or more ait-stmts that 
declare the alternate string characters used by this formatter, 
alt-stmt : altst ringchar a 11 - s t r i n g std-string 

T he aitstringchar statement describes alternate representations for string characters. For example the-mm macro package 
of trotf represents the German "a-umlaut" as a\*:, whileT eX uses the sequence! 11 a. If the troft versions are declared as the 
standard versions using stringchar, theT eX versions may be declared as alternates by using the statement: 
aitstringchar \\\"a a\\* 

When the aitstringchar statement is used to specify alternate forms, all forms for a particular formatter must be declared 
together as a group. Also, each formatter or macro package must provide a complete set of characters, both uppercase and 
lowercase, and the character sequences used for each formatter must be completely distinct. Character sequences that 
describe uppercase and lowercase versions of the same printable character must also be the same length. It may be necessary 
to define some new macrosforagiven formatter to satisfy these restrictions. (The current version of buiidhash does not 
enforce these restrictions, but failure to obey them may result in errors being introduced into files that are processed with 
ispeii.) 

An important minor point isthat ispeii assumes that all characters declared as wordchars or boundarychars will occupy 
exactly one position on the terminal screen. 
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A single character-set statement can declare either a single character or a contiguous range of characters. A range is given as in 
egrep and the shell: [a-z] means lowercase alphabetics; i‘a-z] meansall but lowercase, and so on. All character-set state¬ 
ments are combined (unioned) to produce the final list of characters that may be part of a word. The collating order of the 
characters is defined by the order of their declaration; if a range is used, the characters are considered to have been declared in 
ASCII order. Characters that have case are collated next to each other, with the uppercase character first. 

The character-declaration statements have a rather strange behavior caused by the need to match each lowercase character 
with its uppercase equivalent. In any given wordchars or boundarychars statement, the characters in each range are first sorted 
into ASCII collating sequence, then matched one-for-onewith the other range. (The two ranges must have the same number 
of characters). Thus, for example the two statements: 

wordchars [aeiou] [AEIOU] 
wordchars [aeiou] [UOIEA] 

would produce exactly the same effect. To get thevowelsto match up "wrong," you would have to use separate statements: 

wordchars a U 
wordchars e 0 
wordchars i I 
wordchars o E 
wordchars u A 

which would cause uppercasee to beO, and lowercase 0 to bee. This should normally be a problem only with languages that 
have been forced to useastrangeASCII collating sequence. If your uppercase and lowercase letters both collate in the same 
order, you shouldn't have to worry about this "feature.” 

The prefixes and suffixes sections have exactly the same syntax, except for the introductory keyword: 

prefixes : prefixes flagdef* 
suffixes : suffixes flagdef* 
flagdef : flag [*jU] char : repl * 

A prefix or suffix table consists of an introductory keyword and a list of flag definitions. Flags can be defined more than once, 
in which case the definitions are combined. Each flag controls one or more repis (replacements), which are conditionally 
applied to the beginnings or endings of various words. 

Flags are named by a single character char. Depending on a configuration option, this character can be either any uppercase 
letter (the default configuration) or any 7-bit ASCII character. M ost languages should be able to get along with just 26 flags. 

A flag character may be prefixed with one or more option characters. (If you wish to use one of the option characters as a flag 
character, simply enclose it in double quotes.) 

The asterisk (*) option means that this flag participates in cross-product formation. T hisonly matters if thefile contains both 
prefix and suffix tables. If so, all prefixes and suffixes marked with an asterisk will be applied in all cross-combinations to the 
root word. For example, consider the root fix with prefixespreand in, and suffixes esand ed. If all flags controlling these 
prefixes and suffixes are marked with an asterisk, then the single root fix would also generate prefix, prefixes, prefixed, infix, 
infixes infixed, fix, fixes, and fixed. C ross-product formation can produce a large number of words quickly, some of which 
may be i llegal, so watch out. If cross-products produce illegal words, munchiist will not produce those flag combinations, and 
theflag will not be useful. 

repl : condition* > [ - strip-string , ] append-st r i ng 

The-option specifies that the associated flag is only active when a compound word is being formed. This is useful in a 
language like German, in which the form of a word sometimes changes inside a compound. 

A t-epi is a conditional rule for modifying a root word. Upto eight conditions may be specified. If theconditionsare 
satisfied, the rules on the rightside of therepi are applied, as follows: 

1. If a strip- st ring is given, it isfirst stripped from the beginning or ending (as appropriate) of the root word. 

2. Theappend-string is added at that point. 



For example, the condition . means "any word", and thecondition y means"any word ending in Y.” T he following (suffix) 
replacements: 

. > MENT 

Y > -Y.IES 

would change induce to inducement and fly to flies. (If they were controlled by thesameflag, they would also change f/yto 
flyment, which might not be what was wanted, munchiist can be used to protect against this sort of problem; seethe 
command sequence given in the next paragraph.) 

N o matter how much you might want it, the strings on the right must be strings of specific characters, not ranges. The 
reasons are rooted deeply in the way ispeii works, and it would be difficult or impossible to provide for more flexibility. For 
example, you might want to write: 

[EY] > - [EY] , IES 

Thiswill notwork. Instead, you must use two separate rules: 

E > -E,IES 

Y > -Y,IES 

The application of repiscan be restricted to certain wordswith conditions 
condition : { . | character | range } 

A condition is a restriction on the characters that adjoin, and/or are replaced by, the right-hand side of the repi. U p to 
eight conditions may be given, which should be enough context for anyone. The right-hand side will be applied only 
if the conditions in therepi are satisfied. The conditions also implicitly define a length; roots shorter than the number of 
conditions will not pass the test. (Asa special case, a condition of a single dot defines a length of zero, so that the rule applies 
to all words indiscriminately.) This length is independent of the separate test that insists that all flags produce an output 
word length of at least four. 

Conditions that are single characters should be separated by whitespace. For example to specify wordsending in ED , write 
this 

E D> -ED,ING # As in covered > covering 
If you write this: 

ED > -ED, ING 

th e effect wi 11 bethesameas 

[ED] > -ED,ING 

As a final, minor but important point, it is sometimes useful to rebuild a dictionary file using an incompatible suffix file. For 
example, suppose you expand the r flag to generate "er" and "ers" (thus making thez flag somewhat obsolete). T o build a 
new dictionary newdict that using new affixes will accept exactly the same list of words as the old list oiddict did using old 
affixes, the-c switch of munchiist is useful, as in the following example: 

$ munchiist -c oldaffixes -1 newaffixes oiddict > newdict 

If you use this procedure, your new dictionary will always accept the same list the original did, even if you badly screwed up 
the affix file. This is because munchiist compares the words generated by a flag with the original word list and refuses to use 
any flags that generate illegal words. (Don't forget that the munchiist step takes a long time and eats up temporary file space.) 

EXAMPLES 

Asan exampleof conditional suffixes, here isthe specification ofthesflag from the English affix file 

flag *S: 

[ A AEI0U]Y > -Y,IES # As in imply > implies 
[AEIOU]Y > S # As in convey > conveys 
[SXZH] > ES # As in fix > fixes 
[ A SXZHY] > S #As in bat > bats 
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The first line applies to wordsending in Y but not in vowel-Y. The second takes care of the vowel-Y words. The third then 
handles those words that end in a sibilant or near-sibilant, and the last picks up everything else. 

N ote that the conditions are written very carefully so that they apply to disjoint sets of words. I n particular, note that the 
fourth line excludes words ending in Y as well asthe obvious SXZ H. Otherwise, it would convert "imply'' into "implys." 

Although the English affix file does not do so, you can also have a flag generate more than one variation on a root word. For 
example, you could extend the English r flag as follows: 

flag *R: 

E > R #As in skate > skater 

E > RS # As in skate > skaters 

[ A AEI0U]Y > -Y,IER # As in multiply > multiplier 

[ A AEI0U]Y > -Y,IERS # As in multiply > multipliers 

[AEIOU]Y > ER # As in convey > conveyer 

[AEIOU]Y > ERS # As in convey > conveyers 

[ A EY] > ER # As in build > builder 

[ A EY] > ERS # As in build > builders 

This flag would generate both "skater" and "skaters" from "skate." This capability can be very useful in languages that make 
use of noun, verb, and adjective endings. For instance, one could define a single flag that generated all the German "weak" 
verb endings. 

SEE ALSO 

ispell(l) 

Local 


ip 

ip— Lineprinter devices. 

SYNOPSIS 

#include <linux/lp.h> 

CONFIGURATION 

ip[02] are character devices for the parallel line printers; they have major number 6 and minor number 02. The minor 
numbers correspond to the printer port base addresses 0x03bc, 0x0378, and 0x0278. Usually, they have mode 220 and are 
owned by root and group ip. You can use printer ports either with polling or with interrupts. Interrupts are recommended 
when high traffic is expected, such as for laser printers. For usual dot matrix printers, polling will usually be enough. The 
default is polling. 

DESCRIPTION 

T he following iocti(2) calls are supported: 

int ioctl(int fd, LPTIME, int arg) 


int ioctl(int fd, LPCHAR, int arg) 


Sets the amount of time that the driver sleeps before rechecking the 
printer when the printer's buffer appears to be filled to arg. If you havea 
fast printer, decrease this number; if you havea slow printer, then 
increase it. T his is in hundredths of a second; the default 2 is 0.05 
seconds. It only influences the polling driver. 

Sets the maximum number of busy-wait iterations that the polling driver 
does while waiting for the printer to get ready for receiving a character to 
arg. If printing is too slow, increase this number; if the system gets too 
slow, decrease this number. The default is 1000. It only influences the 
polling driver. 
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int ioctl(int fd, LPABORT, int arg) 
int ioctl(int fd, LPABORTOPEN, int arg) 
int ioctl(int fd, LPCAREFUL, int arg) 

int ioctl(int fd, LPWAIT, int arg) 


int ioctl(int fd, LPSETIRQ, int arg) 

int ioctl(int fd, LPGETIRQ, int *arg) 
int ioctl(int fd, LPGETSTATUS, int *arg) 

LP_PBUSY 
LP_PACK 
LP_POUTPA 
LP_PSELECD 
LP_PERRORP 

int ioctl(int fd, LPRESET) 

FILES 

/dev/lp* 

AUTHORS 

The printer driver was originally written by Jim Weigand and LinusT orvalds. It was further improved by M ichael K. 
Johnson. The interrupt code was written by N igel Gamble. Alan Cox modularized it. lpcareful, lpabort, lpgetstatus were 
added by Chris M etcalf. 

SEE ALSO 

mknod(l), chown(l), chmod(l), tunelp(8), lpcntl(8) 

15 January 1995 

mem, kmem, port 

mem, kmem, port— System memory, kernel memory, and system ports 

DESCRIPTION 

mem is a character device file that is an image of the main memory of the computer. It can be used, for example, to examine 
(and even patch) the system. 


If arg iso, the printer driver will retry on errors; otherwise it will abort. 
The default iso. 

If arg iso, open(2) will be aborted on error; otherwise, the error will be 
ignored. The default is to ignore it. 

If arg iso, then the out-of-paper, offline, and error signals are required to 
befalseon all writes; otherwise, they are ignored. The default is to ignore 
them. 

Sets the number of busy-wait iterations to wait before strobing the printer 
to accept a just-written character and the number of iterations to wait 
before turning the strobe off again to arg. The specification says this time 
should be 0.5 microseconds, but experience has shown the delay caused 
by the code is already enough. For that reason, the default value is o. This 
is used for both the polling and the interrupt driver. 

ThisioctiQ requires superuser privileges. It takes an int containing the 
new IRQ as argument. As a side effect, the printer is reset. When arg is 0 , 
the polling driver will be used, which is also default. 

Stores the currently used IRQ in arg. 

Stores the value of the status port in arg. The bits have the following 
meaning: 

Inverted busy input, active high 
Unchanged acknowledge input, active low 
Unchanged out-of-paper input, active high 
Unchanged selected input, active high 
U nchanged error input, active low 

Refer to your printer manual for the meaning of the signals. N otethat 
undocumented bits can also beset, depending on your printer. 

Resets the printer. N 0 argument is used. 




Part IV: Special Files 



Byte addresses in mem are interpreted as physical memory addresses. References to non-existent locations cause errors to be 
returned. 

Examining and patching is likely to lead to unexpected results when read-only or write-only bits are present. 

It is typically created by 

nknod -m 660 /dev/mem c 1 1 
chown root.mem /dev/mem 

T he file kmem is the same as mem, except that the kernel virtual memory rather than physical memory is accessed. 

It is typically created by 

mknod -m 640 /dev/kmem c 1 2 
chown root.mem /dev/kmem 

port is si milar to mem, butthelO ports are accessed. 

It is typically created by 

mknod -m 660 /dev/port c 1 4 
chown root.mem /dev/port 


FILES 

/dev/mem 

/dev/kmem 

/dev/port 

SEE ALSO 

mknod(l), chown(l), ioperm(2) 
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mouse— Serial mouse interface. 

CONFIG 

Serial mice are connected to a serial RS232/V24 dialout line; seecua(4) for a description. 

DESCRIPTION 

The pinout of the usual 9 pin plug as used for serial mice is 


Pin Name Used for 


2 

RX 

Data 


3 

TX 

-12 V, Imax: 

= 10 mA 

4 

DTR 

+12 V, Imax 

= 10 mA 

7 

RTS 

+12 V, Imax 

= 10 mA 

5 

GND 

Ground 



Thisisthespecification; in fact, 9 V sufficeswith most mice 

The mouse driver can recognize a mouse by dropping RTS to low. About 14ms later, the mouse will send 0x4D on the data 
line After a further 63ms, M icrosoft-compatible mice will send 0x33. Other mice send different values. 
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The relative mouse movement is sent asdx (positive means right) and dy (positive means down). Various mice can operate at 
different speeds. To select speeds, cycle through the speeds 9600, 4800, 2400, and 1200 bits/sec, each time writing the two 
characters from the table below and waiting 0.1 seconds. The following table shows available speeds and the strings that 
select them: 

Bitsfsec String 

9600 
4800 
2400 
1200 

Thefirst byteof a data packet can beused to synchronization purposes. 

MICROSOFT PROTOCOL 

TheM icrosoft protocol usesl start bit, 7 data bits, no parity, and 1 stop bit at the speed of 1200 bits/sec. Data is sent to 
RxD in 3-byte packets. The dx and dy movements are sent as two's-complement, ib (rb) is set when the left (right) button is 
pressed: 


Byte 

d6 

d5 

d4 

d3 

d2 

dl 

dO 

1 

1 

Ib 

rb 

dy7 

dy6 

dx7 

dx7 

2 

0 

dx5 

dx4 

dx3 

dx2 

dxl 

dxO 

3 

0 

dy5 

dy4 

dy3 

dy2 

dyl 

dyO 


Original M icrosoft mice have only two buttons. H owever, there are some three-button mice that also use the M icrosoft 
protocol. Pressing thethird button is reported by sending a packet with zero movement and no buttons pressed. 

M0 USESYSTEMS PROTOCOL 

TheM ouseSystems protocol uses 1 start bit, 8 data bits, no parity, and 2 stop bits at the speed of 1200 bit^sec. Data is sent 
to RxD in 5-byte packets, dx is sent as the sum of the two two's-complement values, dy is send as negated sum of the two 
two's-complement values, ib (mb, rb) iscleared when the left (middle, right) button ispressed: 


Byte 

dl 

d6 

d5 

d4 

d3 

d2 

dl 

dO 

1 

1 

? 

7 

7 

7 

Ib 

mb 

rb 

2 

0 

dxa6 

dxa5 

dxa4 

dxa3 

dxa2 

dxal 

dxaO 

3 

0 

dxb6 

dxb5 

dxb4 

dxb3 

dxb2 

dxbl 

dxbO 

4 

0 

dya6 

dya5 

dya4 

dya3 

dya2 

dyal 

dyaO 

5 

0 

dyb6 

dyb5 

dyb4 

dyb3 

dyb2 

dybl 

dybO 

SUN PROTOCOL 








The Sun protocol uses 1 start bit, 8 data bits, no parity, and 2 stop bits at the speed of 1200 bit^sec. Data is sent to RxD in 

3-byte packets, dx is sent as single two's-complement value, dy as negated two's-complement value, ib (mb, rb) iscleared when 

the left (middle, right) button ispressed: 






Byte 

dl 

d6 

d5 

d4 

d3 

d2 

dl 

dO 

1 

1 

? 

7 

7 

7 

Ib 

mb 

rb 

2 

0 

dx6 

dx5 

dx4 

dx3 

dx2 

dxl 

dxO 

3 

0 

dy6 

dy5 

dy4 

dy3 

dy2 

dyl 

dyO 


*q 

*p 

*o 

*n 
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MM PROTOCOL 

TheM M protocol usesl start bit, 8 data bits odd parity, and 1 stop bit at the speed of 1200 bits/sec. Data is sent to RxD in 
3-byte packets, dx and dy are sent as single signed values, the sign bit indicating a negative value. ib (mb, rb) is set when the 
left (middle, right) button is pressed: 


Byte 

d7 

d6 

d5 

d4 

d3 

d2 

dl 

dO 

1 

1 

? 

7 

dxs 

dys 

Ib 

mb 

rb 

2 

0 

dx6 

dx5 

dx4 

dx3 

dx2 

dxl 

dxO 

3 

0 

dy6 

dy5 

dy4 

dy3 

dy2 

dyl 

dyO 


FILES 

/dev/mouse a commonly used symlink pointing to a mouse device 

SEE ALSO 

cua(4), bm(4) 

Linux, 10 February 1996 


null, zero 

null, zero — Datasink. 

DESCRIPTION 

Data written on a nun or zero special file is discarded. 

Readsfrom thenuii special file always return end of file, whereas reads from zero always return \0 characters. 

nun and zero are typically created by 

mknod -m 666 /dev/null c 1 3 
mknod -m 666 /dev/zero c 1 5 
chown root.mem /dev/null /dev/zero 

NOTES 

If these devices are not writableand readable for all users, many programs will act strangely. 

FILES 


/dev/null 

/dev/zero 


SEE ALSO 

mknod(l), chown(l) 


Linux, 21 November 1992 
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ram— Ram disk device. 



DESCRIPTION 

ram isa block device to access the ram disk in raw mode. 

It is typically created by 

mknod -m 660 /dev/ram b 1 1 
chown root.disk /dev/ram 

FILES 

/dev/ram 

SEE ALSO 

mknod(l), chown(l), mount(8) 


scf 
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sd 

sd— D river for SCSI diskdrives. 

SYNOPSIS 

#include <linux/hdreg.h> 

CONFIG 

The block de/ice name has the following form: sdip, where 1 is a letter denoting the physical drive, and p is a number 
denoting the partition on that physical drive. Often, the partition number, p, will be left off when the device corresponds to 
thewholedrive. 

SCSI disks have a major device number of 8 and a minor device number of the form (16 *drive_number) +partition_number, 
where drive_number is the number of the physical drive in order of detection and partition_number is as follows: 

Partition 0 Thewholedrive 

Partitions 1-4 T he D 0 S "primary'' partitions 

Parti tions 5-8 The DOS "extended" (or "logical”) partitions 

For example, /dev/sda will have major 8 and minor 0 and will refer to all the first SC SI drives in the system; /dev/sdb3 will 
have major 8 and minor 19 and will refer to the third DOS "primary” partition on the second SCSI drive in the system. 

At this time, only block devices are provided. Raw devices have not yet been implemented. 

DESCRIPTION 

The following ioctis are provided 

HDIO_REQ 


A pointer to this structure is passed as the iocti(2) parameter. 

The information returned in the parameter is the disk geometry of the 
drive as understood by DO SIT his geometry is not the physical geometry 
ofthedrive. Itisusedwhen constructing the drive's partition table, 


Returns the BIOS disk parameters in the following structure: 

struct hd geometry { 

unsigned char heads; 

unsigned char sectors; 

unsigned short cylinders; 

unsigned long start; 

}; 
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however, and is needed for convenient operation of fdisk(l), etdisk(l), 
and iiio(l). If thegeometry information is not available zero is returned 
for all the parameters. 

blkgetsize Returns the device size in sectors The iocti(2) parameter should be a 

pointer to along. 

blkrrpart Forces a reread of the SC SI disk partition tables. N o parameter is 

needed. 

Thescsi(4) ioctis are also supported. If the ±octi(2) parameter is 
required and it is null, then ±octi(2) will return -einval. 

FILES 

/dev/sd [ a - h ]: The whole device 

/dev/sd [ a - h ] [ 0 - 8 ]: Individual block partitions 

SEE ALSO 

scsi(4) 

17 December 1992 


St 

st— SCSI tape device. 

SYNOPSIS 

#include <sys/mtio.h> 

int ioctl(int fd, int request [, (void *)arg3]) 
int ioctl(int fd, MTIOCTOP, (struct mtop *)mt_cmd) 
int ioctl(int fd, MTIOCGET, (struct mtget *)mt status ) 
int ioctl(int fd, MTIOCPOS, (struct mtpos *)mt_pos ) 

DESCRIPTION 

The st driver provides the interface to a variety of SCSI tape devices. Currently, the driver takes control of all detected 
devices of type sequential-access. T he st driver uses major device number 9. 

Each device uses two minor device numbers: a principal minor device number, n, assigned sequentially in order of detection, 
and a no-rewind device number, (n +128). Devices opened using the principal device number are sent a rewind command 
when they are closed. Devices opened using the no-rewind device number are not. Options such as density or block size are 
not coded in the minor device number. These options must beset by explicit ioctif) calls and remain in effect when the 
device is closed and reopened. 

D evices are typically created by 

mknod -m 660 /dev/st0 c 9 0 
mknod -m 660 /dev/stl c 9 1 
mknod -m 660 /dev/nst0 c 9 128 
mknod -m 660 /dev/nstl c 9 129 

There is no corresponding block device. The character device provides buffering and read-ahead by default and supports 
reads and writes of arbitrary size (limited by the driver's internal buffer size, which defaults to 32768 bytes but can be 
changed either by using a kernel startup option or by changing a compile-time constant). 

D evice /dev/tape is usually created as a hard or soft link to the default tape device on the system. 



St 



ioctlS 

The driver supports three iocti requests. Requests not recognized bythest driver are passed to the scsi driver. The 
definitions below are from /usr/inciude/iinux/mtio.h: 


mtioctop! PERFORM A TAPE OPERATION 

This request takes an argument of type (struct mtop *). N otall drives support all operations. The driver returns an EIO 
error if the drive rejects an operation. 

/* Structure for MTIOCTOP - mag tape op command: */ 
struct mtop { 

short mt_op; /* operations defined below */ 
int mt_count; /* how many of them */ 

}; 


M agnetic tape operations: 

MTBSF 

MTBSFM 

MTBSR 

MTBSS 

MTEOM 

MTERASE 

MTFSF 

MTFSFM 

MTFSR 

MTFSS 

MTNOP 

MTOFFL 

MTRESET 

MTRETEN 

MTREW 

MTSEEK 


MTSETBLK 

MTSETDENSITY 


MTWEOF 

MTWSM 


Backward space over mt_count filemarks. 

Backward space over mt_count filemarks. Reposition the tape to theEOT 
sideof the last filemark. 

Backward space over mt_count records (tape blocks). 

Backward space over mt_count setmarks. 

Go to the end of the recorded media (for appending files). 

E rase tape. 

Forward space over mt_count filemarks 

Forward space over mt_count filemarks Reposition the tape to theBOT 
sideof the last filemark. 

Forward space over mt_count records (tape blocks). 

Forward space over mt_count setmarks. 

No op; flushes the driver's buffer as a side effect. Should be used before 
readi ng status with mtiocget. 

Rewind and put thedriveoff line. 

Reset drive. 

Retention tape. 

Rewind. 

Seek to the tape block number specified in mt_count. This operation 
requires either a SCSI-2 drive that supports the locate command (device¬ 
specific address) or aTandberg-compatibleSCSI-1 drive (Tandberg, 
Archive Vi per, W angtek,...). The block number should be one that was 
previously returned bynuiocpos because thenumber is device-specific. 

Set the drive's block length to the value specified in mt_count. A block 
length of zero sets the drive to variable block size mode. 

Set the tape density to the code in mt_count. Some useful density 
codes are 

18 0x00 Implicit 0x11 QIC-525 

0x04 QIC-11 0x12 QIC-1350 

0x05 QIC-24 0x13 DDS 

0X0F QIC-120 0x14 Exabyte EXB-8200 

0x10 QIC-150 0x15 Exabyte EXB-8500 

Write mt_count filemarks. 

Writemt count setmarks 
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MTSETDRVBUFFER 


MT_ST_BUFFER WRITES 


MT_ST_ASYNC_WRITES 


MT_ST_READ_AHEAD 


MT_ST_TWO_FM 


MT_ST_DEBU6GING 

MT_ST_FAST_EOM 


Set various drive and driver options according to bits encoded in 
mt_count. These consist of the drive's buffering mode, six Boolean driver 
options, and the buffer write threshold. These parameters are initialized 
only when the device isfirst detected. The settings persist when the device 
isclosed and reopened. A single operation can affect just the buffering 
mode, just theBoolean options, or just the write threshold. 

A value having zeros in the high-order 4 bits will be used to set the drive's 
bufferi ng mode. T he bufferi ng modes are: 

0 Thedrivewill notreportGOOD statuson writecommandsuntil 

the data blocks are actually written to the medium. 

1 T he drive may report good status on write commands as soon 
as all the data has been transferred to the drive's internal 
buffer. 

2 The drive may report good status on write commands as soon 
as all the data has been transferred to the drive's internal buffer 
and all buffered data from different initiators has been 
successfully written to the medium. 

T o control the write threshold, thevaluein mt_count must include the 
constant mt_st_write_threshold logically 0 Red with a block count in the 
low 28 bits The block count refers to 1024-byte blocks, not the physical 
block size on thetape. The threshold cannot exceed the driver's internal 
buffer size (see the descri ption). 

To set and clear theBoolean options thevaluein mt_count must include 
the constant mt_st_booleans logically 0 Red with whatever combination 
of the following options is desired. Any options not specified are set false. 
TheBoolean optionsare 

(D efault: true) Buffer all write operations. If this option isfalseand the 
drive uses a fixed block size, then all write operations must be fora 
multiple of the block size. This option must beset false to write reliable 
multi-volume archives. 

(D efault: true) W hen this options istrue, write operations return 
immediately without waiting for the data to be transferred to the drive if 
the data fits into the driver's buffer. T he write threshoId determi nes how 
full the buffer must bebeforea new SCSI write command is issued. Any 
errors reported by thedrivewill beheld until the next operation. This 
option must be set false to write reliable multi-volume archives. 

(D efault: true) T hisoption causes the driver to provide read buffering 
and read-ahead. If this option isfalseand the drive uses a fixed block size, 
then all read operations must be for a multiple of the block size. 

(D efault: false) This option modifies the driver behavior when a file is 
closed. The normal action isto write a single filemark. Iftheoption is 
true, thedriverwill write two filemarks and backspace over the 
second one. 

Note that this option should not be set true for QIC tape drives because 
they are unable to overwrite a filemark. These drives detect the end of 
recorded data by testing for blank tape rather than two consecutive 
filemarks 

(D efault: false) This option turnson various debugging messages from 
the driver (effective only if the driver was compi led with debug defined). 

(D efault: false) This option causes the mteom operation to be sent directly 
to thedrive, potentially speeding up the operation but causing the driver 
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to lose track of the current file number normally returned by the mtiocget 
request. I f mt_st_fast_eom isfalse, the driver wi II respond to an mteom 
request by forward spacing over files. 

Example: 

struct mtop mt _c md; 

mt _ c md. mt _ o p = MTSETDRVBUFFER; 

mt _ c md. mt _ c o u n t =MT_ST_BOOLEANS | 

MT_ST_BUFFER_WRITES | 

MT_ST_ASYNC_WRITES; 
ioctl (f d, MTIOCTOP, & mt _ c md); 


MTIOCGET: GET STATUS 

This request takes an argument of type (struct mtget *). The driver returns an EIO error if the drive rejects an operation. 

/* structure for MTIOCGET - mag tape get status command */ 
struct mtget { 
long mt_type; 
long mt_resid; 

/* the following registers are device dependent */ 
long mt_dsreg; 
long mt_gstat; 
long mt_erreg; 

/* The next two fields are not always used */ 
daddr_t mt_fileno; 

daddr_t mt_blkno; 


T he header fi le defines many values for mt_type, but the current driver reports only the generic types mt_isscsii (G eneric 
SC SI-1 tape) and mt_isscsi 2 (Generic SCSI-2 tape). 


mt_resid is always zero. (Not implemented for SC SI tapedrives.) 

mtdsreg reports the drive's current settings for block size (in the low 24 bits) and density (in thehigh 8 bits). These fields are 
defined by mt_st_blksize_shift, mt_st_blksize_mask, mt_st_density_shift, and mt_st_density_mask. 


mt_gstat reports generic (device independent) status information. T he header file defines macros for testing these status bits: 
gmt_eof ( x ) T he tape is positioned just after a filemark (always false after an mtseek 

operation). 

The tape is positioned at the begi nni ng of the fi rst file (always false after 
an mtseek operation). 

A tape operation has reached the physical End of T ape. 

The tape is currently positioned at asetmark (always false after an mtseek 
operation). 

Thetape is positioned at the end of recorded data. 

The drive is write-protected. Forsomedrivesthiscan also mean that the 
drive does not support writing on the current medium type. 

The last openo found thedrivewith atapein place and ready for 
operation. 

This generic status information reports the current density setting for 
9-track tape drives only. 

The drive does not have a tape i n place. 

Immediate report mode (not supported). 


GMT_B0T(X) 

GMT_EOT(X) 

GMT_SM(X) 

GMT_E0D(x) 

GMT_WR_PROT (X) 

GMT_0NLINE(X) 

GMT_D_6250(X), GMT_D_1600(X), GMT_D_800(X) 

GMT DROPEN(X) 

GMT_IM_REP_EN(X) 


mt_erreg: The only field defined in mt_erreg is the recovered error 
count in the low 16 bits (as defined by mt_st_softerr_shift and 
mt_st_softerr_mask). Dueto inconsistencies in theway drives report 
recovered errors, thiscount is often not maintained. 
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mt_f iieno reports the current file number (zero-based). This value is set to 
-i when thefile number isunknown (such as after mtbss orMTSEEK). 
mt_bikno reports the block number (zero-based) within the current file. 
This value is set to -i when the block number isunknown (such as after 

MTBSF, MTBSS, OrMTSEEK). 

MTIOCPOS: GET TAPE POSITION 

This request takes an argument of type (struct mtpos *) and reports the drive's notion of the current tape block number, 
which isnotthesarneasmt_bikno returned by mtiocget. This drive must be a SC SI-2 drive that supports the read position 
command (device-specific address) or aT andberg-compatible SCSI-1 drive (T andberg, Archive Vi per, W angtek,...). 

/* structure for MTIOCPOS - mag tape get position command */ 
struct mtpos { 

long mt_blkno; /* current block number */ 

}; 

RETURN VALUE 

EIO 

ENOSPC 

EACCES 

ENXIO 
EBUSY 
EOVERFLOW 

EINVAL 
ENOSYS 

COPYRIGHT 

Copyright 1995, Robert K. N ichols. 

Permission is granted to makeand distribute verbatim copies of this manual, provided thecopyright notice and this 
permission notice are preserved on all copies. Additional permissions are contained in the header of the source file. 

SEE ALSO 

mt(l) 

Linux 1.1.86, 31 January 1995 

tty 

tty— C ontrolling terminal. 

DESCRIPTION 

Thefile /dev/tty is a character file with major number 5 and minor number 0, usually of mode 0666 and owner, group 
root. tty. It is a synonym for the controlling terminal of a process, if any. 

In addition to theioctio requests supported by the device that tty refers to, the following ioctio request is supported: 


T he requested operation could not be completed. 

A write operation could not be completed because the tape reached end- 
of-medium. 

An attempt was made to write or erase a write-protected tape. (Thiserror 
is not detected during openo.) 

D uring openi ng, the tape device does not exist. 

The device is already in use or the driver was unable to allocate a buffer. 
An attempt was made to read or write a variable-length block that is 
larger than the driver's internal buffer. 

An ioctio had an illegal argument, or a requested block sizewasillegal. 
Unknown ioctio. 
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tiocnotty Detach the current process from its controlli ng termi nal and removeit 

from its current process group, without attaching it to a new process 
group (that is, set its process group ID to zero). This ioctio call only 
works on file descriptors connected to /dev/tty; this is used by daemon 
processes when they are invoked by a user at a terminal. T he process 
attempts to open /dev/tty; if the open succeeds, it detaches itself from the 
terminal by using tiocnotty, but if the open fails, it is obviously not 
attached to a terminal and does not need to detach itself. 


FILES 

/dev/tty 

SEE ALSO 

mknod(l), chown(l), getty(l), termios(2), console(4), ttys(4) 
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ttys— Serial terminal lines. 

DESCRIPTION 

tty s [ 0 - 3 ] are character devices for the serial terminal lines. 
They are typically created by 

mknod -m 660 /dev/ttyS0 c 4 64 # base address 0x03f8 

mknod -m 660 /dev/ttySI c 4 65 # base address 0x02f8 

mknod -m 660 /dev/ttyS2 c 4 66 # base address 0x03e8 

mknod -m 660 /dev/ttyS3 c 4 67 # base address 0x02e8 

chown root.tty /dev/ttyS[0-3] 

FILES 

/dev/ttyS[0 - 3] 

SEE ALSO 

mknod(l), chown(l), getty(l), tty(4) 


Linux, 19 December 1992 


vcs, vcsa 

vcs, vcsa— Virtual console memory. 

DESCRIPTION 

/dev/vcso is a character device with major number 7 and minor number 0, usually of mode 0644 and owner root. tty. 

11 refers to the mem o ry of th e cu rrentl y d i spl ayed virtual console terminal. 

/dev/vcs [ i -63] are character da/ices for virtual console terminals; they have major number 7 and minor number 1 to 63, 
usually mode 0644 and owner root.tty. /dev/vcsa[o-63] arethesamebut include attributes and are prefixed with four bytes, 
giving the screen dimensions and cursor position: lines, columns, x, y.(x = y = 0 at the top-left corner of the screen.) 
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These replace the screen dump ioctisof consoie(4), so the system administrator can control access using filesystem permis¬ 
sions. 

T he devices for thefirst eight virtual consoles may be created by 

for x in 0 1 2345678; do 
mknod -m 644 /dev/vcs$x c 7 $x; 
mknod -m 644 /dev/vcsa$x c 7 $[$x+128]; 
done 

chown root.tty /dev/vcs* 

N o ioctif) requests are supported. 

EXAMPLES 

You can do a screendump on vt3 by switching to vtl and typing cat /dev/vcs3 >foo. 

This program displays the character and screen attributes under the cursor of the second virtual console and then changes the 
background color there: 

#include <unistd.h> 

#include <stdio.h> 

#include <fcntl.h> 

void main() 

{ int fd; 

struct {char lines, cols, x, y;} scrn; 
char ch, attrib; 

fd = open("/dev/vcsa2", 0_RDWR); 

(void)read(fd, &scrn, 4); 

(void)lseek(fd, 4 + 2*(scrn.y*scrn.cols + scrn.x), 0); 

(void)read(fd, &ch, 1); 

(void)read(fd, &attrib, 1); 

printf("ch='%c 1 attrib=0x%02x\n", ch, attrib); 

attrib A = 0x10; 

(void)lseek(fd, -1, 1); 

(void)write(fd, &attrib, 1); 

} 

FILES 

/dev/vcs[0 - 63] 

/dev/vcsa[0-63] 

AUTHOR 

Andries Brouwer (aeb@cwi.ni) 

HISTORY 

Introduced with version 1.1.92 of the Linux kernel. 

SEE ALSO 

console(4), tty(4), ttys(4), selection(l) 


Linux, 19 February 1995 
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intro 

intro— Introduction to file formats. 

DESCRIPTION 

Thischapter describes various fileformats and protocols and theused C structures if any. 

AUTHORS 

Look at the header of the manual page for the authors and copyright conditions. Note that these can be different from page 
to page! 

Linux, 24July 1993 


active, active.times 

active, active.times— List of activeUsenet newsgroups. 

DESCRIPTION 

The file /news/iib/active lists the newsgroups that the local site receives. Each newsgroup should be listed only once. Each 
line specifies one group; their order in the file does not matter. W ithin each newsgroup, articles are assigned unique names, 
which are monotonically increasing numbers. 

If an article is posted to newsgroups not mentioned in this file, those newsgroups are ignored. If no valid newsgroups are 
specified, the article is filed into the newsgroup "junk" and only propagated to sites that receive the "junk” newsgroup. 

Each line consists of four fields specified by a space 

na me hi ma r k I o ma r k flags 

T he first field is the name of the newsgroup. Newsgroupsthat start with thethree characters to. are treated specially; see 
mnd(8). The second field is the highest article number that has been used in that newsgroup. The third field is the lowest 
article number in the group; this number is not guaranteed to be accurate and should only betaken as a hint. N otethat 
because of article cancellations, there may be gaps in the numbering sequence. If the lowest article number is greater than the 
highest article number, there are no articles in the newsgroup. T o make it possible to update an entry in-place without 
rewriting the entire file, the second and third fields are padded with leading zeros to make them a fixed width. 

Thefourth field can contain one of the following flags: 
y Local postings are allowed 

n No local postings are allowed, only remote ones 

m Thegroup ismoderated and all postingsmust be approved 

j Articles in thisgroup are not kept but only passed on 

x Articles cannot be posted to this newsgroup 

=f oo. bar Articles are locally filed into the f oo. bar group 

If a newsgroup has the j flag, then no articles will be filed into that newsgroup and local postings to that group should not be 
generated. If an article for such a newsgroup is received from a remote site it will be filed into the "junk” newsgroup if it is 
not cross-posted. This is different from not having a newsgroup listed in the file because sites can subscribe to j newsgroups 
and the article will be propagated to them. 

If thefourth field of a newsgroup starts with an equal sign, then the newsgroup is an alias. Articles can be posted to thegroup 
but will be treated as if they were posted to thegroup named after the equal sign. The second and third fields are ignored. 

N otethat the newsgroup header is not modified (Alias groups are typically used during a transition and are typically created 
with ctiinnd(8)). An alias newsgroup should not point to another alias. 
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The file /news/iib/active. times provides a chron ologi cal record of when newsgroups are created. This file is normally 
updated by innd(8) whenever a ctiinnd newgroup command is done. Each line consist of three fields: 

n a me t i me creator 

The first field is the name of the newsgroup. The second field is the time it was created, expressed as the number of seconds 
si nee the epoch— a time_t; see gettimeofday(2). The third field is the electronic mail address of the person who created the 
group. 

HISTORY 

W ritten by Rich $alz (nsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

ctlinnd(8), innd(8) 


adduser.conf 

adduser.conf —Configuration filefor adduser(8) and addgroup(8). 

SYNOPSIS 

/etc/adduser.conf 


DESCRIPTION 

The file adduser.conf contains defaults for the programs adduser(8) and addgroup(8). Each option takes the form opt i on = 

v a I ue. 


The valid configuration options are 


DSHELL 

DHOME 

SKEL 

FIRSTJJID 

USERGROUPS 


USERS_GID 


The login shell to be used for all new users. Defaults to /bin/bash. 

The directory in which new home directories should be created. Defaults to /home. 

The directory from which skeletal user configuration files should be copied. Defaults to / 
etc/skel. 

Specifies the lowest valid U ID for normal users on your system. IDsbelow firstjjid are 
reserved for administrative and system accounts. Defaults to 1000 . 

TheusERGRoups variablecan be either yes or no. If yes, each created user will be given their 
own group to use as a default, and their setup will arrange to have them create files group- 
writable by default, thus allowing them to effectively use group-writeablefilespace areas 
(such as /usr/iocai). If no, each created user will be placed in the group whose G ID is 
users_gid, and they will create files not group-writeable by default. 

If usergroups is no, then usersjiid istheGID given to all newly created users. The default 
value is 100 . 


FILES 

/etc/adduser.conf 

SEE ALSO 

adduser(8) 


DebianGNU/Linux version 1.94 
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aliases 

aliases —Aliases file for sendmail. 

SYNOPSIS 

aliases 

DESCRIPTION 

This file describes user ID aliases used by. The file resides in and is formatted as a series of lines of the form: 
n a me: n a me _ 1, n a me _ 2, n a me _ 3, ... 

Thename isthenameto alias, and thename.n are the aliases for that name Lines beginning with whitespace are continuation 
lines. Lines beginning with # are comments. 

Aliasing occurs only on local names. Loops cannot occur because no message will be sent to any person more than once. 

After aliasing has been done, local and valid recipients who have a .forward file in their home directory have messages 
forwarded to the list of users defined in that file. 

This is only the raw datafile; the actual aliasing information is placed into a binary format in the files and using the program 
newaiiases(l). A newaiiases command should be executed each time the aliases file is changed for the change to take effect. 

SEE ALSO 

newaiiases(l), dbm(3), sendmaii(8), "Sendmail Installation and Operation Guide," "Sendmail: An Internetwork M ail 
Router.” 

BUGS 

Because of restrictions in dbm(3), a single alias cannot contain more than about 1000 bytes of information. You can get longer 
aliases by "chaining"— that is, making the last name in the alias a dummy name that is a continuation alias. 

HISTORY 

The aliases file format appeared in BSD 4.0. 

BSD 4,10 May 1991 


cfingerd 

cfingerd— Configurable finger daemon. 

SYNOPSIS 

cfingerd [-c|-d J-e J-o|-v] 

-c Check configuration 

-d Run as daemon, not inetd 

-e Emulate local finger without inetd 

-o Turn off all finger queries 

-v Request version information 

-c checks your installed configuration. This makes sure there are no existing errors in the current cfingerd. conf file. 

-d runs cfingerd as a daemon. D on't run cfingerd this way if you're using inetd. 

-e allows you to emulate a local finger on a user that exists on your system. This makes it so that you can test cfingerd on 
your system before installing it. Using the -e directive is the same as installing the software, typing finger username® and 
getti ng the output. Using -e username does the same. 



cfingerd 



-o turns off all finger queries. This makes it so that no one can finger your system— no matter what they try to do. 

-v requests cfingerd version information. 

DESCRIPTION 

cfingerd is a totally new and totally configurable finger daemon— one of the first. It utilizes the finger port (port 79) to 
provide useful information on each user on your system. H owever, cfingerd provides a unique twist. 

cfingerd was designed for the sole purpose of making output on finger queries configurable. If you want to change any text 
that is displayed during finger queries, you can configure the finger daemon to display just about anything you want. 

cfingerd also takes into account any security breaches and attempts to close them. With .nofinger files, this is displayed 
instead of finger information, making it possible for users to keep themselves relatively anonymous from outside users. 

WHY WAS IT DONE? 

Theanswer issimple: security. M any sites turn off finger for the reason that the/don't want outside users to seewho'son 
their system or get information about a specific user on their system. This seemed unfair to the rest of the users out there, so 
this program was created. Those sites were waiting for this type of program. M any sites that originally had their finger turned 
off turned them back on because of cfingerd. 

M any sites complai ned that they wanted the capabi lity to create a fake user or a user that doesn't exist but calls a prewritten 
shell script, cfingerd takes this into account and provides the best method possible for creating such scripts (See 
cfingerd. conf (5) for more information on the configuration file) 

FEATURES Cfingerd PROVIDES AND DESCRIPTIO N S 0 F EACH 

cfingerd was totally rewritten. Why is this? The older version of cfingerd had quite a few bugs, and it didn't quite do all the 
things that cfingerd now does. This new version was totally revamped, and most of the bugs that were in the older version of 
cfingerd were removed in this one. The code is also more compact. 

H eader and footer displays were a big part of the original release of cfingerd and shall continue to remain in all versions. 

H eadersand footers are only displays at the beginning and ending of all finger displays and are used as unique little 
adverti sements 

The last time displayed is always a critical issue. It'scovered in cfingerd. cfingerd simply shows how many times this user is 
connected, what their idle time is on each tty they're connected to, and whether the/ are accepting messages. If they're not 
accepting messages, a [mesg-nj display will be shown. This display also shows the last time mail was read and whether this 
user has mail. 

Stand-alone and inetd support is compiled into the program, but only inetd support is given for the time being. The reason 
is that I have not yet added the option for stand-alone daemon mode. 

.nofinger files are used when a user wants to remain anonymous. These files should be placed in their home directories and 
can display anything they want. There'sjust a few restrictions. These .nofinger display files cannot be character devices, 
directories, FIFOs, soft or hard links, or anything else of that caliber. They must only be normal files. 

Fake users were supported for the simple fact that many sites want to create users who don't exist and make them execute a 
shell. If you want this done install a fake user. Read cfingerd. conf (5) for more information on these useful options. 

Service displays were used to show what fake users you have installed on your system. These can be formatted however you 
want and are explained in cfingerd.conf (5). 

Searching for usernames is a powerful feature that cfingerd takes full advantage of. If you are looking for a specific username 
on the system or don't know what their name is simply use the search, username directive with cfingerd, and you can search 
for a user on your system. 

Searching for usernames is not case sensitive. If you are searching for a specific username or part of the user's name, chances 
are that it’ll be displayed. 
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There's also an option to display your public PGP key if you have one. This is very useful if you want to keep your mail or 
other information secret to yourself and don't want "big brother" watching over your shoulder as you talk among yourselves. 
(Thanks to Andy Smith for this patch.) The standard plan file is .plan, project is .project, and PGP info is. pgpkey. 

Remember, any or all of these options stated can be turned on or off at will. If you want a specific option turned off, turn it 
off. 

ERROR MESSAGES 

Any error messages that result are fairly easy to debug if you know what to look for. 

Segmentation violations don’t always occur, but if they ever do, you can pretty easily figure out what's going on. Unfortu¬ 
nately, cfingerd doesn't have any compatibility with older cfingerd.cont files, so if you get a segmentation violation, this 
means (usually) that your cfingerd.cont file needs to be replaced. 

Time-outs usually mean that a script has timed out or a connection to another site timed out. 

SYSLOGGING MESSAGES 

There's no real way to descri be syslog messages because they can be changed as the system administrator chooses. Although, 
examples can be given based on the standard configuration that was distributed. 

If any IP addresses cannot be matched to a hostname, SYSLOG will display ip: Hostname not matched. 

If the renice fails (to makethe program run at the highest priority), then syslog will display Fatal - Nice died: (reason). 
Ifthereisno buffer information iswaiting in thesTDiN buffer, syslog will display stdin contains no data. 

If a trusted host fingers your site, a<- Trusted will appear. 

If a rqected host fingers your site, a<- Rejected will appear. 

If root is fingered on your site, it will display Root. 

If a service listing was fingered on your site, syslog will display service listing. 

If a user listing was requested, syslog will display user listing. 

If a fake user was requested, syslog will display Fake user. 

If whois data was requested, syslog will display whois request. (N ote that whoiswas not implemented in this release because 
it wasn't RFC compliant.) 

Any extra information pertaining to the incoming finger is displayed in the sysloggi ng area. (It's also recommended that you 
reconfigure syslog.conf (5) to display to an unused VT.) 

BUGS 

When data is forwarded to other sites for fingering, it shows the output of the system that it forwarded the finger request to. 
This has got to change. 

On ELF-specific systems, services lists usually show a bit of garbage at the beginning of the finger display. This doesn't 
appear to beaproblem on a.out systems, so if you haveELF, you might want to compileefingerd asa.out if this becomes a 
problem. 

PLANS 

Any other optionsor improvements will probably comefrom user suggestions. 

Later plans wi II mean you can defineyour own display formats for thefinger display. This means that you can redefinehow 
you want your finger display to look. 

CONTACTING 

If you like the software and you want to learn more about it or want to see a feature added to it that isn't already here, write 
to khollisObitgate.com. 
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I've received calls at work pertaining to the software, and although I appreciate the fact that people like the software I wrote, 
I'd appreciate it if you leave me e-mail and be considerate. 

cfingerd isnow being maintained by M ichael Jarvis. Any additions after cfingerd 1.2.3 should be directed toward M ichael. 

YOU Can reach him at mjarvis@qns.com. 

If you want to see other projects that Bitgate Software is currently developing, check out the Web page at http:// 
www.bitgate.com/. This will contain all the update information on the software that is being developed and that is already 
released. 

SEE ALSO 

cfingerd.conf(5), finger(l), userlist(l), syslog.conf(5) 

cfingerd 1.2.3, 24 M ay 1996 


cfingerd.conf 

cfingerd.conf — C onfigurablefinger daemon configuration file. 

SYNOPSIS 

/etc/cfingerd.conf 

DESCRIPTION 

cfingerd.conf is the configuration file for cfingerd. This has been totally rewritten to support a more readable configuration 
file. This version of the new configuration file is not compatible with the older versions from 1.0.3 or earlier. 

Each line in the configuration file is split into three sections: files, config, and hosts. Each one of those sections issplit into 
subsections. 

Subtext of each option is either Boolean options, string options, or switchable options, all changeable by the system 
administrator. 

Each section issplit into a series of sections that resembles C-type definition; it's not exact but close enough to be familiar. 
There's only one exception: These are not case sensitive. Any casing will do as long as the option is legal. 

Thus, each option is formatted likethis: 

OPTION sub_option_name = { 

(tab/space) string_option = "string format", 

(tab/space) boolean_option = [BOOL, BOOL], 

(tab/space) +/-internal_config_option 
(tab/space) host.name.here 
} 

Thisshowsthat string options are strings put into quotes, Boolean options are given as true and false, switchable options 
are given with the + or - directive, and hostnames are used as substrings so that wildcards are not necessary. 

You can add comments using the hash mark (#) at the beginning of the line. Please note that no comments are allowed inside 
of an option. 

DISPLAY FILES SECTION (FILES display files) 

Each option here is a string option. These are formatted as the example shows. 

plan is the plan file that is used when displaying apian. The standard here is .plan. 

project isthe project file that is used when displaying a project description. T he standard here is .project. 

pgp_key is the Pretty-Good-Privacy file that is shown when displaying a public or private key. The standard here is. pgpkey. 
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(The preceding three files must be world readable but should not be world writable. This makes sure that ctingerd can read 
the file once it becomes the "nobody" UID/GID.Thisis generally a good idea for protection.) 

no_finger is the file that is shown when a user wants to remain anonymous. This is usually the case with root users (which 
should be standard anyway). The standard here is .nofinger. This file can only be a standard displayablefile 

logfile is the file that is used to keep logs of everything that happens to both your system and the finger program. These logs 
are kept as backups for your finger file and can be used to guard against attacks agai nst your system if a finger attack occurs 
Remember, the ctingerd. conf file is root owned, so this file should be kept in a safe hidden place. 

header_display is the fi le that isdisplayed atthetop of each finger display. T he standard hereis/etc/cfingerd/ 
top_finger.txt. 

footer_display is the fi le that isdisplayed at the end of each finger display. The standard hereis/etc/cfingerd/ 
bottom_finger.txt. 

no_user_banner is the fi le that isdisplayed if the user doesn't exist. The standard hereis/etc/cfingerd/nouser_banner.txt. 

no_name_banner is the fi le that isdisplayed if no name was specified in a finger display. This is used in conjunction with the 
SYSTEM_LIST option (explained later). The Standard hereiS/etc/cfingerd/noname_banner.txt. 

rejected_banner isthefilethat isdisplayed if a rejected host tries to finger your system for any reason. The standard here is/ 
etc/ctingerd/rejected_banner.txt. 

FINGER DISPLAY CONFIGURE SECTION (CONFIG finger display) 

Each option in this section is Boolean. The way this works is as follows: The first Boolean option is the setting for a remote 
host or a host that fingers you from the outside. The second Boolean option is the setting for the local host or trusted host. 
This is what people from your own system will see. 

Each option has a - or + option. This is for user- overridable options, which will be in the next release of cfingerd. These will 
allow users to manipulate if this information isdisplayed when that specific user is fingered. 

header file displays the header fi le at the begi nni ng of each fi nger query. 

footer file displays the footer file at the end of each finger query. 

login_id displays the login ID ofthat particular user. 

real_name displays the real name of that particular user. 

directory displays the user's directory. 

shell displays the user's shell. 

room_number displays the user's room number. 

workjjumber displays the user's work phone number. 

home_number displays the user's home phone number. 

other displays the user'sother information. 

last_timejin displays the last time the user logged into the fingered system. 
if_online displays whether the user is currently logged into thefingered system. 
time_mail_read displays the last time that the fingered user read mail. 
day_mail_read displays the last day that the fingered user read hisorher mail. 
origination displays the site from which the user logged in (if applicable). 
plan displays the user's plan file. 
project di splays the user's project fi le. 
pgp displays the user's Pretty-G ood-Privacy key fi le. 



cfingerd.conf 


1111 


no_name_banner displays the banner if no username was given. 

rejectedbanner displays the rqected banner if the site fingering your system was i n the banned- site listi ng. 
system_list displays the system list if one was requested. 
no name displays the no-name display file if no user was selected. 

INTERNALCONFIG CONFIGURE SECTION (CONFIG internal config) 

Each item in this section is a switchable option. This means that a + before the item is turned on and a - before the item is 
turned off. 

allow_multiple_finger_display allowsyou to give a sorted output of all users on more than one specific system. This is useful 
when you have more than one ISP machine located in different cities or a/en states. 

allow_searchable_finger allowsyou to let others outsideyour system (or within it) to search for a specific username by using 
the search. user name directive. 

allow_no_ipjiatch_finger allowsyou to let sites finger your system if a hostname could not be matched to their IP address 
successfully. 

allow_user_override will allow your users to override specific options in the finger display section that you enable. 

allow_userlist_only will allow other sites that are fingering your system for a specific compiled user list to finger your system 
and get a user listing of who's online. This could be a security risk, so you might want to turn this option off if you feel it's a 
security risk. 

allow_finger_forwarding will allow other sites to forward finger requests to a different machine if the user could not be 
located on the current machine. (In order to use this option, you must have the hosts finger forward option set and have 
other sites in there.) 

allow_strict_formatting makes thefinger display remove all returns between display options. This makes the finger display 
look horrible (as with GNU Finger or the other generic fingers) and makes your system look, well, "generic.'' 

allow_verbose_timestamping makes the ti mestamp that is displayed (at any place) very verbose. For instance, where it used to 
say 

On since Sat Aug 12 03:43PM(PDT) 

would now be shown as 

On since Sat Aug 12, 1995 03:43PM(PDT) 

(Basically, allow_verbose_timestamping just takes up more room on the display field.) 

allow_nonident_access lets you only allow connectionsfrom sites that run theident daemon (or RFC 1413-compliant 
program.) This is for security sake and isagood measure against unknown users trying to finger your system. Ifthisoption is 
enabled, users who do not haveidentd running on their system (such as W i ndows users) will be able to finger your system. 
Systems not running identd will return unknown as the user ID and will not be permitted to finger a user on your system. 

allow^finger_logging enables cfingerd to usetheLOGFUE file to store any logs of activity that happen to your system via 
finger. 

allowj_ine__parsing makes cfingerd parse each line of every display file (including the plan, project, and pgp files) for any 
efingerd-specifics commands. If any are found, cfingerd will parse these commands and display correct information 
accordingly. Otherwise, if thisisturned off, the display will appear without parsed commands. 

allow_execution will allow users to execute scripts in place of their .plan, .project, and .pgp files. Thisisused to display the 
standard output of another program directly to the screen of the user. Keep in mind that this is a huge security risk if you 
choose to use it. It's normally suggested that this option remain off, but you can turn it on if necessary. N evertheless, these 
programs are called as nobody, nog roup. 
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allow_fakeuser_finger turnson or off the fake user option in cfingerd. If you want fake users to be defined and available to 
be fingered, you will want to enable this option. This can be a security risk in some instances if you allow for searchable 
fingers and your script calls an execute routine on that variable. Chances are that'll never happen. 

allowjjserlog will allow usersto keep track of who has fingered them and at what time A little file called .fingeriog will 
appear in their directory, which they can examine to see who has fingered them. If you don't care about this, you can disable 
it. Otherwise it’s not a bad idea. (It also logs root fingers as well.) 

SYSTEM LIST SITES CON FIGURE SECTION (CONFIG system list sites) 

T his is just a series of hostnames that you want to finger when displaying your user-list display. If you have more than one 
system that you want to show, simply put their hostname in this list, separated on a line by itself. 

For example, if I have a separate ISP system that I'm running on the side, say chatiink.com, I would change my configuration 
to say 

CONFIG system_list_sites = { chatlink.com, local host } 

Remember, if you are listing only a couple of sites, list the sites you will want to have listed (in order) first. The ending entry 
must be i oca i host or the finger listing will not include your site. If you include local host anywhere else in the list, it will 
stop onceit has reached thei ocai host entry, so remember to list it last! 

I want to get a user listing from my own machine and from chatiink. corn's system. This would be automatically formatted 
nicely (sorted and parsed) and would display on thescreen in sorted order. Thisprogram is usually used in tandem with the 
supplied useriist(l) program. 

If no system list sites are specified, multiple system sites will not be specified. 

TRUSTED HOST SECTION (HOSTS trusted) 

This is a listing of the sites that you allow to finger your system exclusively, giving them the same access that your local users 
would get. I n other words, they aretreated asi ocai host users. 

Each site that you list in this section should be separated by using the, directive. You can include up to 80 sites in this 
listing. 

Wildcards are supported in this section, and you can use them in the regex format as well. Any wildcards with *, ?, or any 
other regex wildcard matching character will work. IP addresses will also work. H ostnames are compared case insensitive. 

REJECTED HOST SECTION (HOSTS rejected) 

This is a listing of the sites that you do not allow to finger your system. These sites don't get to finger anyone (or anything 
for that matter) on your system, regardless of what they try to do. In essence finger is cut off to that particular system. 

Each site that you list in this section should be separated by using the, directive. You can include up to 80 sites in this 
listing. 

Wildcards are supported in this section, and you can use them in the regex format as well. Any wildcards with *, ?, or any 
other regex wildcard matching character will work. IP addresses will also work. H ostnames are compared case insensitive. 

FORWARDED HO ST SECTION (HOSTS finger forward) 

This is a listing of sites that are used to forward a finger query to when a finger request was processed but that particular user 
was not found on the associated system. It will step through this listing, and it will search for the user in question. If the user 
could not be found, then it will step through to the next host and the next, until it finds one. 

Each site that you list in this section should be separated by using the, directive. You can include up to 80 sites in this 
listing. 

Wildcards are supported in this section, and you can use them in the regex format as well. Any wildcards with *, ?, or any 
other regex wildcard matching character will work. H ostnames are compared case insensitive. 

If you do not specify any forwarding sites in this section, finger forwarding will be disabled for your system. 
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FINGER STRINGSCONFIGURE SECTION (CONFIG finger strings) 

Each option in this section is a string that can be changed to fityour needs when displaying finger information. These strings 
are limited to about 20 characters on the display. (If you use more than 20, the finger display will end up looking strange.) 

user_name is the stri ng that isdisplayed when the user's username is shown. 

real_name is the stri ng that isdisplayed when the user's real nameisshown. 

directory is the stri ng that isdisplayed when the user's directory isshown. 

shell isthe string that isdisplayed when the user's shell isshown. 

room_number is the string that isdisplayed when the user's room number isshown. 

work_number is the string that isdisplayed when the user's work phone number isshown. 

home_number is the string that isdisplayed when the user's home phone number isshown. 

other is the string that isdisplayed when the user's other display information is show. 

plan is the string that isdisplayed when theuser'splan isshown. 

project is the string that isdisplayed when the user's project isshown. 

pgpkey isthestring that isdisplayed when theuser's PGP key isshown. 

no plan is the string that isdisplayed when the user doesn't have a plan file to show you. 

no project isthestring that isdisplayed when the user doesn't have a project file to show you. 

no_pgp isthestring that isdisplayed when the user doesn't have a PGP key file to show you. 

wait isthestring that isshown when the system gathers information from other sites for a user listing. 

INTERNAL STRINGSCONFIGURE SECTION (CONFIG internal strings) 

These strings are changeable and can beany length you want (within reason). These strings are concatenated into the 
syslogging display when the appropriate finger has been issued. This section also includes error messages that may occur. 

no_ip_host isshown when there is no hostname that matches the incoming IP address. This usually indicates that either the 
site didn't register its IP address with the I nterN 1C or it is coming from a hacked site. 

renice_fatal isshown when the system failed to change the execution priority on the current process of cfingerd. 

stdin_empty isshown when the input buffer on thecfingerd port isempty. (This should never really happen; it'sherefor 
sanity.) 

trusted_host isshown when a trusted host fingers your system. If you do not specify a trusted host, cfingerd will insert 
ocai host intothisfield. 

rejected_host isshown when a rejected host fingers your system. If you do not specify a rejected host, cfingerd will insert 
0 . 0 . 0.0 into thisfield. 

root_finger isshown when a user fingers root. 

service_finger isshown when a user requests fake user services from your system. 
user_list isshown when a user requests a user listing from your system. 
fakejjser isshown when a user fingers a fake user from your system. 

whoisjjser isshown when a user fingers a user with aWHOIS query. (Thisoption is not yet available.) 

fingerdeny isshown when a user tries to finger with a forward request such as u s e r @h o s 11 @h o s 12 . This is not supported 
because it could result in finger loops and a lot of traffic. 

SIGNAL STRINGSCONFIGURE SECTION (CONFIG signal strings) 

This section is used in changing the output that is given when a system crashes, or a signal is caught, and reported to the 
finger output. 
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T he supported caught signals are as follows: 

SIGHUP, SIGINT, SIGQUIT, SIGILL, SIGTRAP, SIGABRT, SIGFPE, SIGUSR 1 , SIGSEGV, SIGUSR 2 , SIGPIPE, SIGALRM, SIGTERM, SIGCONT, 
SIGTSTP, SIGTTIN, SIGTTOU, SIGIO, SIGXCPU, SIGXFSZ, SIGVTALRM, SIGPROF, SIGWINCH 

FINGER PRO GRAMS FILES SECTION (FILES finger programs) 

These are the programs that are cal led when a specific action istake on thefinger display. 

finger is the file that is used when a user listing is requested from your machine. This is used in the standard user list and in 
thesorted user list, so it iswiseto use the standard here: /usr/sbin/useriist. 

whois is the program that is used when a WH OIS request is done on a specific user. 

FINGER FAKE USERS FILES SECTION (FILES finger fakeusers) 

These are the ever-popular fake users that you can create on your system. These users are ones that don't exist (and should 
not exist, for that matter). These are instead, treated as normal scripts that can be called for your use. 

The format is as follows for fakeusers: 

fake username Seri pt name SEARCHBOOL scri pt 

f ake.user name is the name of the fake user you want to request. M ake sure that this is a user that does not exist on your 
system. Keep in mind that if you create a fake username and that user already exists, the fake username will be shown. 

Seri p t _ n a me is the standard name of your script. This is used in the display of your services listing. 

searchbool specifi es whether parameters can be sent to that specific fake user. If you decide to use the searchbool option 
(true in this case), the passed variables are 


$1 

First passed option 

$2 

Second passed option 

$3 

Third passed option 

$4 

Fourth passed option 


(If more than four options were passed to this, the request will be ignored, and an error message will be returned to the user 
who requested thefinger request.) 

scr i pt is the location of your script. It should bechmod 700 and readable only by root. 

If you do not specify any fake users, a fake user called None will be created. This is a fake user that does nothing and calls/ 
dev/nuii for the script. 

SERVICES HEADER CON FIGURE SECTION (CONFIG services header) 

T his is the display that is given duri ng a services finger. 11 should be formatted the same way that you want it to di splay on 
the screen. 

When specifying thefinger formatted options, you should specify them asC formatted strings as well, with thestandard 
options. This should always be given last in the display. 

An example of this is 

Welcome to this system's services! 

User: Service name: Searchable: 

%-8s %-20s %‘S 

Remember to keep theformat string last or a sigsegv will result. 

SERVICESPOSITIONSCONFIGURESECTION (CONFIG services positions) 

This specifies where in the preceding display string that the information from a service listing is to appear. These numbers 
can be anywhere between 1 and 3. 
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user specifies the position of the username listing. 
service specifies the position of the service full-name listing. 
search specifies the position of the Boolean search display. 

CONTACTING 

If you like this program and have questions or comments about the program's functionality or what- have- you, write to 
khollis@bitgate.com. 

As always, I appreciate any suggestions or bug reports you might have, so bring them on! 

SEE ALSO 

cfingerd(8), cfingerd.text(5), userlist(l), finger(l), regex(3), regexp(3) 

16 May 1996 


cfingerd text rul es 

EXPLANATION 

cfingerd offers different commands that can be placed in text files to display corresponding information. Each command 
used with cfingerd in text files begins with a dollar sign ($). This usually indicates to cfingerd that when it's displaying a file 
it parses the command directly after that character. 

If you want to display a raw $ sign, simply put two $ signs together, or$$. 


TEXT COMMANDS 

The following is a list of text commands and what they do. Each of the text commands can be in any text case; it doesn't 
matter. 


$CENTER 

$DATE 

$TIME 

$IDENT 

$COMPILE_DATETIME 

SVERSION 

$EXEC 


D isplays the entire contents of the line. This command must start at the beginning of the 
line This isa very common command. 

D isplays the current system date in theformat of M M/D D/YY. 

D isplays the current system timein theformat H H :M M A/PM (timezone). 

D isplays the identity of the current person fingering your system. 

D isplays the date and time of which the current issue of cfingerd was compiled on your 
system. 

D isplays the current version of cfingerd. 

Executes a file with x parameters after it. T he $EX EC command must be on a line by itself 
in order to function properly. The command is executed as nobody, nogroup. 


SEE ALSO 

cfingerd (8), cfingerd. conf(5), finger(l), userlist(l), any Of the included dOCSwith thestandard cfingerd distribution. 

cfingerd 1.2.1, 6 ] 30 1996 
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control.cti— Specify handling of U senet control messages. 
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DESCRIPTION 

The file /news/iib/controi.cti is used to determine what action is taken when a control message is received. It is read by the 
parsecontroi script, which is called by all the control scripts (For an explanation of how the control scripts are invoked, see 

innd(8).) 

The file consists of a series of lines; blank lines and lines beginning with a number sign (#) are ignored. All other lines consist 
of four fields separated by a colon: 

message : f r o m :n e wsgroups : a c t i on 

Thefirst field is the name of the message for which thislineisvalid. 11 should be either the name of the control message, or 
theword ail to mean that it is valid for all messages. 

Thesecond field is a shell-style pattern that matches the e-mai I address of the person posting the message. (Theposter's 
address is first converted to lowercase.) The matching is done using the shell's case statement; see sh(l) for details. 

If the control message is newgroup or rmgroup, then the third field specifies the shell-style pattern that must match the group 
being created or removed. If the control message is of a different type, then this field is ignored. 

The fourth field specifies what action to take if this line is selected for the message. The following actions are understood: 

doit The action requested by the control message should be performed. In most cases, the control script 

will also send mail to Usenet. 

doitarg If the control message has an argument, thisistreated asadoit action. If no argument was given, it 

istreated as a mail entry. This is used in a sendsys entries script so that a site can request itsown 
newsfeeds(5) entry by posting a sendsys mysite article On the Other hand, sendsys bombs ask that 
the newsfeeds file be sent; if you usedoifarg, such messages will not be processed automatically. 
doit=f i i e The action is performed, but a log entry is written to the specified log file, file. If rtf e is the word 

man, then therecord ismailed. A null string is equivalent to /dev/nuii. A pathname that starts with 
a slash is taken as the absolute filename to use as the log. All other pathnames are written to /var/ 
log/news/file .log. T he log is written by writelog (see newslog(8)). 
drop N o action istaken; the message is ignored. 

log A one-line log notice is sent to standard error, innd normally directs this to thefile/var/iog/news/ 

errlog. 

iog=f i i e A log entry is written to the specified log file, f i i e, which is interpreted as described previously, 

mail A mail message is sent to the news administrator. 

Lines are matched in order; the last match found in the file is the one that is used. For example, with thefollowing three 
lines: 

newgroup:*:*:drop 

newgroup:tale@*.uu.net:comp.*|misc.*}news.*|rec.*|sci.*|soc.*jtalk.*: doit 
newgroup:kre@munnari.oz.au:aus.*:mail 

A newgroup coming from tale at aUU N ET machine will be honored if it is in the mainstream U senet hierarchy. If kre 
posts a newgroup message creating aus. too, then mail will be sent. All other newgroup messages are ignored. 

HISTORY 

W ritten by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

innd(8), newsfeeds(5), scanlogs(8) 

CVS 

cvs— C oncurrent Versions System support files. 




CVS 


1117 


SYNOPSIS 

$CVSROOT/CVSROOT/commitinfo,v 
$CVSROOT/CVSROOT/cvsignore,v 
$CVSROOT/CVSROOT/cvswrappers,v 
$CVSROOT/CVSROOT/editinfo,v 
$CVSROOT/CVSROOT/history 
$CVSROOT/CVSROOT/loginfo,v 
$CVSROOT/CVSROOT/modules,v 
$CVSROOT/CVSROOT/rcsinfo,v 
$CVSROOT/CVSROOT/taginfo,v 

DESCRIPTION 

cvs isasystem for providing source control to hierarchical collections of source directories. Commands and procedures for 
using cvs are described in cvs(l). cvs manages source repositories, the directories containing master copies of the revision- 
controlled files, by copying particular revisions of the files to (and modifications back from) developers' private working 
directories. In terms of file structure, each individual source repository is an immediate subdirectory of scvsroot. The files 
described here are supporting files; they do not have to exist for cvs to operate, but they allow you to make cvs operation 
more flexible. 

You can use the modules file to define symbolic names for col lections of source maintained with cvs. If there is no modules 
file, developers must specify complete pathnames (absolute or relative to $cvsroot) for the files they want to manage with cvs 
commands. You can usethecommitinto file to defi ne programs to execute whenever cvs commit is about to execute. These 
programs are used for"precommit" checking to verify that the modified, added, and removed files are really ready to be 
committed. Some uses for this check might be to turn off a portion (or all) of the source repository from a particular person 
or group or perhaps to verify that the changed fi les conform to the site's standards for coding practice. 

You can usethecvswrappers file to record cvs wrapper commands to be used when checking files into and out of the 
repository. W rappers allow the file or directory to be processed on the way in and out of cvs. The intended uses are many; 
one possible use is to reformat a C file before the file is checked in so all the code in the repository looks the same. You can 
use the loginfo fileto define programs to execute after any commit, which writes a log entry for changes in the repository. 
These logging programs might be used to append the log message to a file or send the log message through electronic mail to 
a group of developers. You can also post the log message to a particular newsgroup. 

You can usethetaginfofileto define programs to execute after any tag or rtag operation. These programs might be used to 
append a message to a file listing the new tag name and the programmer who created it, to send mail to a group of develop¬ 
ers, or to post a message to a particular newsgroup. You can usethercsinfofileto define forms for log messages. You can use 
theeditinfo file to defi ne a program to execute for editing or validating cvs commit log entries. This is most useful when used 
with a rcsint o forms specification because it can verify that the proper fields of the form were filled in by the user commit¬ 
ting the change. You can use the cvsignore fileto specify the default list of files to ignore during update. You can use the 
history fileto record the cvs commands that affect the repository. The creation of this file enables history logging. 

FILES 

modules The modules fi le recordsyour definitions of names for collections of source code. 

cvs will use these definitions if you use cvs to check in a file with the right 
format to $cvsR00T/cvsR00T/moduies, v. T he modules file can contain blank lines 
and comments (lines beginning with #) as well as module definitions. Long lines 
can be continued on the next line by specifying a backslash (\) as the last 
character on the line. A module definition is a si ngle line of the modules file in 
either of two formats. In both cases, mname represents the symbolic module name 
and the remainder of the line is its definition, 
mname -a aliases ... 

This represents the si mplest way of defining a module mname . T he -a flags the 
definition as a simple alias: cvs will treat any use of mname (as a command 
argument) as if the list of names a i i ases had been specified instead, aliases may 
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contain either other module names or paths When you use paths in a i i ases.cvs 
checkout creates all intermediate directories in the working directory, just as if the 
path had been specified explicitly in thecvs arguments, 
mname [ options ] dir [ files ... ] [&mo d u I e ...] 

In the simplest case, this form of module definition reduces to mname di r .This 
defines all thefilesin directory di r as module mname di r is a relative path (from 
$cvsroot) to a directory of source in one of the source repositories. In this case, 
on checkout, a single directory called mname is created as a working directory; no 
intermediate directory levels are used by default, even if di r was a path involving 
several directory levels. By explicitly specifying files in the module definition after 
dir, you can select particular files from directory di r .The sample definition for 
modules is an example of a module defined with a single file from a particular 
directory. H ere is another example 

m4test unsupported/gnu/m4 foreach.m4 forloop.m4 

With this definition, executing cvs checkout nrnest will create a single working 
directory m4test containing thetwo files listed, which both comefrom a 
common directory several levels deep in thecvs source repository. A module 
definition can refer to other modules by including &modui e in its definition. T he 
checkout command creates a subdirectory for each such module in your working 
directory. New in cvs 1.3; avoid thisfeature if sharing module definitions with 
older versions of cvs. 

Finally, you can use one or more of the following options in module definitions: 
-d name namestheworking directory something other than the module name. 
This option is new in cvs 1.3; avoid thisfeature if sharing module definitions 
with older versions of cvs.-i prog allows you to specify a program prog to run 
whenever files in a module are committed, prog runs with a single argument, the 
full pathname of the affected directory in a source repository. The commitinfo, 
loginto, and editinfo files provide other ways to call a program on commit, -o 
prog allows you to specify a program prog to run whenever files in a module are 
checked out. prog runswith a single argument, the module name, -e prog allows 
you to specify a program prog to run whenever files in a module are exported, 
prog runswith a single argument, the module name.-t prog allows you to 
specify a program prog to run whenever filesin a moduleare tagged, prog runs 
with two arguments: the module name and the symbolic tag specified to rtag. -u 
prog allows you to specify a program prog to run whena/er cvs update is executed 
from the top-level directory of the checked-out module.prog runswith asingle 
argument, the full path to the source repository for this module, 
commitinfo, loginto, ncsinto, editinfo T hese files all specify programs to call at different points in the cvs commit 

process. They have a common structure. Each line is a pair of fields: a regular 
expression, separated by whitespace from afilenameor command-line template. 

W henever one of the regular expression matches a directory name in the 
repository, the rest of the line is used. If the line beginswith a# character, the 
entire line is considered a comment and is ignored. Whitespace between the 
fields is also ignored. Forioginfo, the rest of thelineisacommand-linetemplate 
to execute. T hetemplates can include not only a program name but also 
whatever list of arguments you want. If you write %s somewhere on the argument 
list, cvs supplies, at that point, the list of files affected by the commit. The first 
entry in the list isthe relative path within thesource repository where the change 
is being made. T he remaining arguments list the files that are being modified, 
added, or removed by this commit invocation. Fortaginfo, the rest of the line is 
a command-linetemplateto execute. T hearguments passed to the command are, 
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in Order, the t a g n a me, o p e r a t i on (add for tag, mov for tag -F, and del for tag -d), 
and repos i tor y, and any remaining are pairs of filename revision. A nonzero exit 
of the filter program will cause the tag to be aborted. For commitinfo, the rest of 
thelineisacommand-linetemplateto execute. The tempi ate can include not 
onlyaprogram name but also whatever list of arguments you want. The full path 
to the current source repository is appended to the template, followed by the 
filenames of any filesinvolved in the commit (added, removed, and modified 
files). For rcsinto, the rest of the line is the full path to a file that should be 
loaded into the log message template. Foreditinfo, the rest of the line is a 
command-line template to execute. The template can include not only a 
program name but also whatever list of arguments you want. Thefull path to the 
current log message template file is appended to the template. You can use one of 
two special strings instead of a regular expression: all specifies a command-line 
template that must always be executed, and default specifies a command-line 
template to use if no regular expression is a match. The commitinfo file contains 
commandsto execute before any other commit activity, to allow you to check 
any conditions that must be satisfied before commit can proceed. T he rest of the 
commit will execute only if all selected commands from thisfileexitwith exit 
status 0 . T he rcsinto fi le al lows you to specify log templates for the commit 
logging session; you can use this to provide a form to edit when filling out the 
commit log. The field after the regular expression, in this file, contains filenames 
(of files containing the logging forms) rather than command templates. The 
editinto fi le allows you to execute a script before the commit starts but after the 
log information is recorded. These "edit" scripts can verify information recorded 
in the log file. If the edit script exits with a nonzero exit status, the commit is 
aborted. Theioginto file contains commands to execute at the end of a commit. 
The text specified as a commit log message is piped through the command; 
typical uses include sending mail, filing an article in a newsgroup, or appending 
to a central file. 

cvsignore, .cvsignore T he default list of files (or sh(l) filename patterns) to ignore during cvs update. 

At startup time cvs loadsthecompiled default list of filename patterns (see 
cvs(l)). T hen the per-repository list included in $cvsR00T/cvsR0OT/cvsignore is 
loaded, if it exists. 

Then theper-user list is loaded from shome/. cvsignore. Finally, as cvs traverses 
through your directories, itwill load any per-directory .cvsignore files whenever 
it finds one. These per-directory files are only valid for exactly the directory that 
contains them, not for any subdirectories. 

history C reate thisfile in $cvsroot/cvsroot to enable history logging (see the description 

Of cvs history). 

SEE ALSO 

CvS(l) 

COPYING 

Copyright® 1992, CygnusSupport, Brian Berliner, andjeff Polk. 

Permission is granted to make and distribute verbatim copies of this manual, provided the copyright notice and this 

permission notice are preserved on all copies. 

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, 

provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 
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Permission is granted to copy and distribute translations of this manual into another language, under the preceding 
conditionsfor modified versions, except that this permission notice may be included in translationsapproved by theFree 
Software Foundation instead of in the original English. 

12 February 1992 


DEVINFO 

devinfo— D evice entry database. 


DESCRIPTION 


devinfo is a text file that describes all the possible devices for a system. It is used by makedev(8) to create special file entries in / 
dev. It may be named either /dev/DEviNFo or /etc/devinfo. Information about custom local devices, if any, should be placed 
in devinfo. local or /etc/devinfo. local, which has the same syntax. 


Thefileformat isfree-form. C, C++, and shell comments are understood. There are basically four statements: 


ignore { pr oc-devi ce... } 
batch { device... } 

block device-spec 
char devi ce-spec 


This causes the specified names to be ignored if found in /proc/devices. 

This creates a "batch"— a collection of devices that will all be created when the batch is 
invoked. For example, in the standard devinfo, "generic" is a batch. 

This defines one or more block devices. 

This defines one or more character devices. 


FH ere i s a sam pledevi ce- spec: 

(std, 1) { 
mem (kmem) : 1 
null (public) : 3 
core ■> “/proc/kcore 11 
} 


This example defines a group of devices called std, with major number 1. Running will create all the devices in the group; 
running, for example, would make just the one device nun. 

It is possible to specify, instead of just std, something like std=foo. In this case, the stuff on the right-hand side of the equals 
sign specifies a name from /proc/devices, and the major number will be retrieved from there if present. If an entry from / 
proc/devices is specified, the explicit major number may be omitted. In this case, if the number is not found in /proc/ 
devices, attempts to create thedevice will be rejected. 

Inside the braces is a list of specific devices. The name in parenthesis is the "class"; this is something specified in MAKEDEv.cfg 
that determines the ownership and permissions of the special file created. In the preceding example, the device mem was set to 
have the class kmem, but nun was set to be public. 0 rdinarily, you'd define public to be mode 666 but kmem to be mode 660 
and owned by group kmem. T he number after the colon is the minor number for this particular device; for instance, 3 for 
null. 

You may also specify a symbolic link with For instance, core was made a link to /proc/kcore. N otethat names may 
contain any characters, but names that contain things other than alphanumerics, dash, and underscore should be put in 
double quotes. 

An entire range of devicescan be created. You may specify a range of numbers in brackets: 
tty[1 -8] (tty) : 1 

T his creates ttyi-ttys with minor device numbers starting with 1. If you specify the range in hex (prefixed by 0 x), thedevice 
names will be created numbered in hex, as is normal for ptys. The range may appear inside the name string, but there may 
only be one range. 
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T here is a special syntax for creating the entire banks of devices for a hard drive: 

hd [ a -d ] 8/64 

What this means is as follows: Create hda, and eight partitions on hda (hdai through hdas), starting with minor number 0. 
Then create hdb, and eight partitions, starting with minor number 64. Then hdc, and so on, with minor number 64*2 = 
128— and so forth. These are automatically placed in the class disk. The necessary groups and batches are created so you can 
ask makedev to create hd or hda or hdai and expect it to do the correct thing. 

Note that simple arithmetic is permitted for specifying the mi nor device number, as this often makes things much clearer 
and less likely to be accidentally broken. 

SEE ALSO 

makedev(8), makedev. cfg(5) 

Version 1.4, January 1995 


environ 

environ— U ser environment. 

SYNOPSIS 

extern char **envi ron; 

DESCRIPTION 

An array of strings called the envi ronment is made available by exec(2) when a process begins. By convention, these strings 
havetheform name =vai ue. Common examples are 

user The name of the logged-in user (used by some BSD-derived programs). 

logname The name of the logged-in user (used by someSystem-V derived programs). 

home A user's login directory, set by iogin(l) from the password file passwd(5). 

lang The name of a locale to use for locale categories when not overridden by lc_all or more 

specific environment variables. 

path The sequence of directory prefixes that sh(l) and many other programs apply in searching 

for afile known by an incomplete pathname. The prefixes are separated by :. 
shell Thefilenameof the user's login shell. 

term Theterminal type for which output isto be prepared. 

Further names maybe placed in the environment by the export command and name=vai ue in sh(l) or by thesetenv command 
if you usecsh(l). Arguments may also be placed in the envi ronment at the point of an exec(2). 

It is risky practice to set name =vai ue pairs that conflict with well-known shell variables. Setting these could cause surprising 
behavior in subshells or system(3) commands. 

SEE ALSO 

login(l), sh(l), bash(l), csh(l), tcsh(l), exec(2), system(3) 

Linux, 21 October 1996 


expire.ctl 

expire. cti— C ontrol file for U senet article expiration. 
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DESCRIPTION 

Thefile /news/iib/expire.cti is the default control file for the expire(8) program, which reads it at startup. Blank lines and 
lines beginning with a number sign (#) are ignored. All other lines should be in one of two formats. 

T he first format specifies how long to keep a record of fully expired articles. This is useful when a newsfeed intermittently 
offers older news that is not kept around very long. (The case of very old news is handled by the -c flag of innd(8).) There 
should only beonelinein this format, which looks like this: 

/remember/:days 

W here days is a floating-point number that specifies the upper limit to remember a M essage-ID, even if the article has 
already expired. (It does not affect article expirations.) 

M ost of the lines in the file will consist of five colon-separated fields, as follows: 
pattern : mo d f I a g: k e e p : d e f a u 11 : p u r g e 

The pat tern field is comma-separated set of single wiidmat(3)-style patterns that specify the newsgroups to which the rest of 
the line applies. Because the file is interpreted in order, the most general patterns should be specified first, and the most 
specific patterns should be specified last. 

Themodf i ag field can be used to further limit newsgroups to which the line applies and should be chosen from the following 
set: 

m Only moderated groups 

u 0 nly unmoderated groups 

a All groups 

The next three fields are used to determine how long an article should be kept. Each field should be either a number of days 
(fractions such as 8.5 are allowed) or the word never. The most common use is to specify the default value for how long an 
article should be kept. The first and third fields— keep and purge — specify the boundaries within which an Expires header 
will be honored. They are ignored if an article has no Expires header. The fields are specified in thefile as "lower-bound 
default upper-bound," and they are explained in this order. Because most articles do not have explicit expiration dates, 
however, the second field tends to be the most important one. 

The keep field specifies how many days an article should be kept before it will be removed. N 0 article in the newsgroup will 
be removed if it has been filed for less than keep days, regardless of any expiration date. If this field is the word never, then an 
article cannot have been kept for enough days so it will never be expired. 

T he def aui t field specifies how long to keep an article if no Expires header is present. If this field is the word never, then 
articles without explicit expiration dates will never be expired. 

The purge field specifies the upper bound on how long an article can be kept. N 0 article will be kept longer than the number 
of days specified by thisfield. All articles will be removed after they have been kept for pur ge days. If purge is the word never, 
then the article will never be deleted. 

It is often useful to honor the expiration headers in articles, especially those in moderated groups. To do this, set keep to zero, 
def a ui t to whatever value you want, and purge to never. T 0 ignore any Expires header, set all three fields to the same value. 

There must be exactly one line with a pat tern of * and a modf 1 ags of a; this matches all groups and is used to set the 
expiration default. It should be the first expiration line. For example: 

## How long to keep expired history 
/remember/:5 

## Most things stay for two weeks 
:A:14:14:14 

## Believe expiration dates in moderated groups, up to six weeks 
:M:1:30:42 

## Keep local stuff for a long time 
foo.*:A:30:30:30 
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HISTORY 

W ritten by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

expire(8), wildmat(3) 

exports 

exports— N FS filesystems being exported. 

SYNOPSIS 

/etc/exports 

DESCRIPTION 

The file /etc/exports serves as the access control list for filesystems that can be exported to N FS clients. It is used by both the 
N FS mount daemon mountd(8) and theN FS file server daemon ntsd(8). 

T he file format is similar to the SunOS exports file, except that sa/eral additional options are permitted. Each linecontainsa 
mount point and a list of machine or netgroup names allowed to mount the filesystem at that point. An optional parenthe¬ 
sized list of mount parameters may follow each machine name. Blank lines are ignored, and a# introduces a comment to the 
end of the line. 

GENERAL OPTIONS 

secure 

ro 

link_relative 


link_absolute 

USERID MAPPING 

ntsd bases its access control to files on the server machine on theU ID andGID provided in each N FS RPC request. The 
normal behavior a user would expect is that she can access her files on the server just as she would on a normal filesystem. 
This requires that the same U ID sand G IDs are used on the client and the server machine. This is not always true, nor is it 
always desi rable. 

Very often, it is not desi rable that the root user on a client machine is also treated as root when accessing files on theN FS 
server. T o this end, UID 0 is normally mapped to a different ID: the so-called anonymous or nobody U ID. This mode of 
operation (called root squashing) isthe default and can be turned off with no_root_squash. 

By default, ntsd tries to obtain the anonymous U ID and G ID by looking up user nobody in the password file at startup 
time. If it isn't found, aU ID and G ID of -2 ( 65534 ) is used. These values can also be overridden by theanonuid and anongid 
options. 

In addition to this, ntsd lets you specify arbitrary U ID sand GIDs that should be mapped to user nobody as well. Finally, 
you can map all user requests to the anonymous U ID by specifying the aii_squash option. 

For the benefit of installations where UID s differ between different machines, ntsd provides a way to dynamically map server 
U ID sto client UID sand vice versa. This is enabled with the map daemon option and uses the ugid RPC protocol. For this 
to work, you have to run the ugidd(8) mapping daemon on theclient host. 


Thisoption requires that requests originate on an Internet port less than ipport reserved 
(1024). Thisoption ison by default. T 0 turn it off, specify insecure. 

Allow only read-only requests on thisN FS volume Thedefault isto allow write requests as 
well, which can also be made explicit by using the ™ option. 

Convert absolute symbolic links (where the link contents start with a slash) into relative 
links by prepending the necessary number of. ./sto get from the directory containing the 
link to the root on the server. This has subtle, perhaps questionable semantics when the file 
hierarchy is not mounted at its root. 

Leave all symbolic links as they are. T his is the default operation. 
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H ere's the complete list of mapping options: 

root_squash M ap requests from UID/GID 0 to the anonymous UID/G ID. N ote that this does not 

apply to any other U ID sthat might be equally sensitive, such as user bin. 
no_root_squash T urn off root squashing. Thisoption is mainly useful for diskless clients. 

squash_uids and squash_gids This option specifies a list of U IDsor G ID sthat should be subject to anonymous mapping. 
A valid list of IDs looks likethis 


all_squash 


map_daemon 


anonuid and anongid 


squash_uids=0-15,20,25-50 

Usually, your squash lists will look a lot simpler, such as 
squash_uids=0-100 

M ap all U ID sand G IDs to the anonymous user. U seful for N FS-exported public FTP 
directories, newsspool directories, and so on. The opposite option isno_aii_squash, which is 
the default setting. 

Thisoption turns on dynamic UID/G ID mapping. Each U ID in an N FS request will be 
translated to the equivalent server U ID, and each U ID in an N FS reply will be mapped the 
other way round. T his option requi res that rpc. ugidd(8) runs on the client host. T he default 
setting ismap_identity, which leaves all U ID s untouched. The normal squash options apply 
regardless of whether dynamic mapping is requested. 

These options explicitly set the U ID and GID of the anonymous account. Thisoption is 
primarily useful for PC/N FS clients, where you might want all requests appear to be from 
one user. As an example, consider the export entry for /home /joe in the section "Example," 
which maps all requests to U ID 150 (which is supposedly that of user joe). 


EXAMPLE 

# sample /etc/exports file 
/ master(rw) trusty(rw,no_root_squash) 

/projects proj*.local.domain(rw) 

/usr *.local.domain(ro) @trusted(rw) 

/home/joe pc001(rw,all_squash,anonuid=150,anongid=100) 

/pub (ro,insecure,all_squash) 

Thefirst line exports the entire fi lesystem to machines master and trusty. In addition to write access, all UID squashing is 
turned off for host trusty. The second and third entry show examples for wildcard hostnames and netgroups (this is the 
entry @t rusted). The fourth line shows the entry for the PC/N FS client discussed previously. The last line exports the public 
FTP directory to every host in the world, executing all requests under the nobody account. The insecure option in this entry 
also allows clients with N FS implementations that don't use a reserved port for N FS. 

CAVEATS 

Unlike other N FS server implementations, this nt sd allows you to export both a directory and a subdirectory thereof to the 
same host, for instance /usr and /usr/xi 1 R6. In this case, the mount options of the most specific entry apply. For instance 
when a user on the client host accesses a file in /usr/xi 1 R6, the mount options given in the /usr/xi 1 R6 entry apply. This is 
also true when the latter isawildcard or netgroup entry. 

FILES 

/etc/exports Configuration file for nf sd(8) 

/etc/passwd T he password file 

DIAGNOSTICS 

An error parsing the file is reported using sysiogd(8) as level notice from a daemon whenever nfsd(8) or mountd(8) is started. 
Any unknown host is reported at that time, but often not all hosts are not yet known to named(8) at boot time so as hosts are 
found, they are reported with the same sysiogd(8) parameters. 



filesystems 



SEE ALSO 

mountd(8), nfsd(8), nfs(5), passwd(5) 


21 October 1996 
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filesystems — Linux filesystem types: minix, ext, ext 2 , xia, msdos, umsdos, vfat, proc, nfs, iso9660, hpfs, sysv, smb, ncpfs. 


DESCRIPTION 


In thefile /proc/fiiesystems, you can find which filesystems your kernel currently supports. (If you need a currently 
unsupported one insert the corresponding moduleor recompile the kernel.) 

Following is a description of the variousfilesystems. 


minix 

ext 

ext2 

xiafs 

msdos 

umsdos 

vfat 

proc 

iso9660 
High Sierra 

Rock Ridge 

hpfs 

sysv 

nfs 


Thefilesystem used in theM inix operating system, the first to run under Linux. It has a number 
of shortcomings: a64M B partition size limit, short filenames, a single time stamp, and so on. It 
remainsuseful for floppies and RAM disks. 

An elaborate extension of the minix filesystem. It has been completely superseded by the second 
version of the extended filesystem (ext 2 ) and will eventually be removed from the kernel. 
Thehigh performance disk filesystem used by Linux forfixed disks aswell as removable media. 
Thesecond extended filesystem wasdesigned as an extension of theextended filesystem (ext). 
ext 2 offers the best performance (in terms of speed and CPU usage) of the filesystems supported 
under Linux. 

Designed and implemented to be a stable safe filesystem by extending theM inix filesystem code. 
It provides the basic, most requested features without undue complexity. T he xia filesystem is no 
longer actively developed or maintained. It isused infrequently. 

Thefilesystem used by DOS, Windows, and some OS/2 computers, msdos filenames can be no 
longer than an eight-character namefollowed by an optional period and three-character 
extension. 

An extended D 0 S fi lesystem used by Linux. It adds capability for long filenames, UID/GID, 
POSIX permissions, and special files (devices, named pipes, and so on) under theD OS 
filesystem, without sacrificing compatibility with D 0 S. 

Extended DOS filesystem used by M icrosoft W indows95 and Windows NT. vfat adds 
capability for long filenames under the MS-DOS filesystem. 

A pseudo-filesystem that isused as an interface to kernel data structures rather than reading and 
interpreting /dev/kmem. In particular, its files do not take disk space. Seeproc(5). 

A CD-ROM filesystem type conforming to the ISO 9660 standard. 

Linux supports H igh Sierra, the precursor to the I SO 9660 standard for CD-ROM filesystems. It 
is automatically recognized within theiso9660 filesystem support under Linux. 

Linux also supports theSystem Use Sharing Protocol records specified by the Rock Ridge 
Interchange Protocol. They are used to further describe the files in theiso9660 filesystem to a 
UNIX host and provides information such as long filenames, UID/GID, POSIX permissions, 
and devices. It is automatically recognized within theiso9660 filesystem support under Linux. 
TheH igh Performance Filesystem, used in OS/2. Thisfi lesystem is read-only under Linux dueto 
the lack of available documentation. 

An implementation of the SystemV/Coherent filesystem forLinux. It implements all XenixFS, 
SystemV/386 FS, and Coherent FS. 

T he network filesystem used to access disks located on remote computers. 
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smb A network filesystem that supports the SM B protocol, used by Windows for Workgroups, 

WindowsNT, and LAN Manager. 

T o use smb, you need a special mount program, which can be found in theksmbts package at 
ftp://sunsite.unc.edu/pub/Linux/system/Filesystems/smbfs. 
ncpfs A network filesystem that supports the N C P protocol, used by N ovell N etW are. 

To use ncpfs, you need special programsfound at ftp: //iinux 0 i .gwdg.de/pub/ncpfs. 

SEE ALSO 

proc(5), fsck(8), mkfs(8), mount(8) 

25 March 1996 
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fstab — Static information about the filesystems. 

SYNOPSIS 

#include <fstab.h> 

DESCRIPTION 

The file fstab contains descriptive information about the various filesystems, fstab is only read by programs and not written; 
it is the duty of the system administrator to properly create and maintain this file. Each filesystem is described on a separate 
line; fields on each line are separated by tabs or spaces. The order of records in fstab is important because fsck(8), mount(8), 
and umount(8) sequentially iterate through fstab doing their thing. 

T he first field (fs_spec) describes the block special de/ice or remote filesystem to be mounted. 

The second field (f s_f lie) describes the mount point for the filesystem. For swap partitions, this field should be specified as 
none. 

The third field (f s_vf stype) describes the type of the filesystem. The system currently supports three types of filesystems: 
minix A local filesystem, supporting filenames of length 14 or 30 characters, 

ext A local filesystem with longer filenames and larger i nodes. T hisfilesystem has been replaced 

by theext 2 filesystem and should no longer beused. 

ext 2 A local filesystem with longer filenames, larger inodes, and a lot of other features. 

xiafs A local filesystem with longer filenames, larger inodes, and a lot of other features. 

msdos A local filesystem for M S-DOS partitions 

hpfs A local filesystem for H PFS partitions. 

iso9660 A local filesystem used for CD-ROM drives. 

nfs A filesystem for mounting partitionsfrom remote systems. 

swap A disk partition to beused for swapping. 

If vfs_f stype is specified as ignore, the entry is ignored. This is useful to show disk partitions that are currently unused. 
Thefourth field (fs_mntops) describes the mount options associated with the filesystem. 

It is formatted as a comma-separated list of options. It contains at least the type of mount plus any additional options 
appropriate to the filesystem type. For documentation on the available optionsfor non-N FS filesystems, seemount(8). For 
documentation on all N FS-specific options, take a look atnfs(5). Common for all types of filesystems are the options noauto 
(do not mount when mount -a is given, such as at boot time) and user (allow a user to mount). For more details, see mount (8). 

The fifth field (fs_treq) is used for these filesystems by thedump(8) command to determine which filesystems need to be 
dumped. If the fifth field is not present, a value of zero is returned and dump will assume that the filesystem does not need to 
be dumped. 
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T he sixth field (fs_passno) isused by thef sck(8) program to determine the order in which filesystem checks are done at 
reboot time. The root filesystem should be specified with ats_passno of i, and other filesystems should haveats_passno of 2 . 
Filesystemswithin adrivewill be checked sequentially, butfilesystemson different drives will be checked at the same time to 
utilize parallelism available in the hardware. If the sixth field is not present or zero, a value of zero is returned and tsck will 
assume that the filesystem does not need to be checked. 

The proper way to read records from fstab isto usetheroutinegetmntent(3). 

FILES 

/etc/fstab 

BUGS 

The documentation in mount(8) i s often more up-to-date. 

SEE ALSO 

getmntent(3), mount(8), swapon(8), nfs(5) 

HISTORY 

The fstab file format appeared in 4.0 BSD. 

Linux0.99, 21November 1993 
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groff_font — Format of groff device and font description files. 


DESCRIPTION 

T he grotf_font format is roughly a superset of theditroff font format. U nlikethe ditnoff font format, there is no associated 
binary format. The font files for device name are stored in a di rectory devn a me. There are two types of file: a device description 
file cal led desc and for each font f, a font file called f. These are text files; there is no associated binary format. 


DESC FILE FORMAT 

The desc file can contain the following types of lines: 


res n 
hor n 
vert n 
sizescale n 


unitwidth n 

tcommand 

sizes si s2 ... sn0 


styles SI S2 ... Sm 
fonts n FI F2 F3 ... Fn 


There aren machine units per inch. 

The horizontal resolution is n machine units. 

T he vertical resolution isn machineunits. 

The scale factor for point sizes. By default, this has a value of 1 . 0 ne scaled point is 
equal to one point/n. T he arguments to the unitwidth and sizes commands are 
given in scaled points. 

Q uantities in the font files are given in machi ne units for fonts whose point size isn 
scaled points 

This means that the postprocessor can handle the t and u output commands. 

This means that the device has fonts at si, s 2 ,... sn scaled points. The list of sizes 
must determinated by ae. Each si can also be a range of sizes m-n. The list can 
extend over more than one line. 

T hefirst m font positions will be associated with styles si... sm. 

Fonts fi... Fn will be mounted in thefont positionsm+1,... ,m+n wherem isthe 
number of styles. This command may extend over more than one line. A font name 
of 0 will cause no font to be mounted on the corresponding font position. 



Part V: File Formats 



family f am T he default font family isf am. 

charset This line and everything foil owing in the file are ignored. It is allowed for the sake of 

backwards compati bi Iity. 

The res, umtwidth, fonts, and sizes lines are compulsory. Other commands are ignored by troff but may be used by 
postprocessors to store arbitrary information about the device in theDEsc file. 

FONT FILE FORMAT 

A font file has two sections. The first section is a sequence of lines, each containing a sequence of blank delimited words; the 
first word in the line is a key, and subsequent words give a value for that key. 

name f T he name of the font is f . 

spacewidth n T he normal width of a space isn. 

slant n T he characters of the font have a slant of n degrees. (Positive means forward.) 

ligatures ligi iig 2 ... lign [ 0 ] C haracters ngi, iig 2 ,... ,iign are ligatures; possi ble ligatures are ff, fi, fi, and ffi. 

For backwards compatibility, the list of ligatures may be terminated with ae. The 
list of ligatures may not extend over more than one line. 

special The font is special; this means that when a character is requested that is not present 

in the current font, it will be searched forin any special fonts that are mounted. 

Other commands are ignored by troff but may be used by postprocessors to store arbitrary information about the font in the 
font file. 

The first section can contain comments which start with the# character and extend to the end of a line. 

The second section contains one or two subsections. It must contain a charset subsection and it may also contain a kernpairs 
subsection. These subsections can appear in any order. Each subsection starts with a word on a line by itself. 

Theword charset starts the charset subsection. The charset line is followed by a sequence of lines. Each linegives 
information for one character. A line comprises a number of fields separated by blanks or tabs. The format is 

n a me me t r i c s type code c o mme n t 

name identifies the character: if name is a single character c, it corresponds to thegroff input character c; if it is of the form \c 
wherec is a single character, then it corresponds to thegroff input character nc; otherwise it corresponds to thegroff input 
character \ [name ] (if it is exactly two characters**, it can be entered as\(**). groff supports eight-bit characters; however, 
some utilities have difficulties with eight-bit characters. For this reason, there is a convention that the name charn is 
equivalent to the single character whose code isn. For example chari63 is equivalent to the character with codel63, which is 
the pounds sterling sign in ISO Latin-1. Thename— isspecial and indicates that thecharacter isunnamed; such characters 
can only be used by means of the \n escape sequence in troff. 

T he t y pe field gives the character type: 

1 The character has an descender, such as p. 

2 The character has an ascender, such as t>. 

3 Thecharacter has both an ascender and a descender, such as (. 

The code field gives the code that the postprocessor uses to print thecharacter. Thecharacter can also be input to groff using 
this code by means of the \n escape sequence. The code can beany integer. If it starts with a 0 , it will be interpreted as octal; 
if it starts with @x or ex, it will be interpreted as hexadecimal. 

Anything on the line after the code field will be ignored. 

T he met r i cs field hastheform: 

width [, height [, depth[, italic_correction[, lett_italic_comection 
^•[,subscri pt correcti on ]]]]] 

There must not be any spaces between these subfields. M issing subfields are assumed to be 0 . The subfields are all decimal 
integers. Because there is no associated binary format, these values are not required to fit into a variable of type char as they 
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are in ditrotf.Thewi dth subfields gives the width of the character. The he i ght subfield gives the height of the character 
(upwards is positive); if a character does not extend above the baseline, it should be given a zero height, rather than a negative 
height. The depth subfield gives the depth of the character, that is, the distance below the lowest point below the baseline to 
which the character extends (downwards is positive); if a character does not extend below above the baseline, it should be 
given a zero depth, rather than a negative depth. T he i t a i i c.c or recti on subfield gives the amount of space that should be 
added after the character when it is immediately to be followed by a character from a roman font. The 
i eftitai i c_correction subfield gives the amount of space that should be added before the character when it is immediately 
to be preceded by a character from a roman font. The subscript_correction gives the amount of space that should be added 
after a character before adding a subscript. This should be less than thei tai i c_cor recti on. 

A line in the charset section can also have the format 

n a me " 

This indicates that name isjust another name for the character mentioned in the preceding line 
Theword kernpairs starts the kernpairs section. Thiscontainsasequenceof linesof theform: 
cl c2 n 

This means that when character ci appears next to character c 2 , the space between them should be increased by n. M ost 
entries in kernpairs section will have a negative value for n. 

FILES 

/usr/iib/groff/font/dev name/DEsc D evice description file for device name. 

/usr/nb/groff/font/devname/F Font file for font f of device name. 

SEE ALSO 

groff_out(5), gtroff(l) 

Groff Vers on 1.09,14 February 1994 
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groft_out— groff intermediate output format. 

DESCRIPTION 

This manual page describes the format output by GN U troff. The output format used by GN U troff is very similar to that 
used by U NIX device-independent troff. 0 nly the differences are documented here. 

Theargumentto thes command isin scaled points (unitsof pointy, where n isthe argument to thesizescaie command in 
theDEsc file.) Theargumentto the* H eight command is also in scaled points 

Thefirst three output commands are guaranteed to be 

x T device 
x res n h v 
x init 

If thetcommand line is present in theDEsc file troff will use the foil owing two commands: 

txxx *x* isany sequence of characters terminated by a space or a newline thefirst 

character should be printed at the current position, thecurrent horizontal position 
should be increased by the width of thefirst character, and so on for each character. 
The width of the character is that given in the font file appropriately scaled for the 
current point size and rounded so that it is a multiple of the horizontal resolution. 
Special characters cannot be printed using this command. 
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unxxx This is same as the t command except that after printing each character, thecurrent 

horizontal position isincreased by the sum of the width of that character and n. 

N otethat single characters can have the eighth bit set, as can the names of fonts and special characters. 

The names of characters and fonts can be of arbitrary length; drivers should not assume that they will be only two characters 
long. 

When a character isto be printed, that character will always be in the current font. U nlike device-independent trotf, it is not 
necessary for drivers to search special fonts to find a character. 

T he d drawing command has been extended. These extensions will not be used by GN U pic if the -n option is given. 

Dt n\n Set the shade of gray to be used for filling solid objects ton; n must bean integer 

between 0 and 1000, where 0 corresponds to solid white and 1000 to solid black and 
values in between correspond to intermediate shades of gray. This applies only to 
solid circles, solid ellipses, and solid polygons. By default, a level of 1000 will be 
used. W hatever color a solid object has, it should completely obscure everything 
beneath it. A value greater than 1000 or less than 0 can also be used: This meansfill 
with the shade of gray that is currently being used for lines and text. N ormally, this 
will be black, but some drivers may provide a way of changing this 
dc d\n Draw a solid circlewith a diameter of d with the leftmost point at the current 

position. 

de dx dy\n D raw a solid ell ipse with a horizontal diameter of dx and a vertical diameter of dy 

with the leftmost point at thecurrent position. 

Dp dxi dyi d x 2 dy 2 ... dxn dy n\n D raw a polygon with, for i = 1,.... n +1, the i th vertex at the current position + 

^’itdxj , dy j ). At the moment, GNU pic only uses this command to generate 
triangles and rectangles. 

dp dxi dyi d x 2 dy 2 ... dxn dy n\n Like Dp, but draw a solid rather than outlined polygon. 

Dt n\n Set the current line thickness to n machine units. Traditionally, U NIX trotf drivers 

use a line thickness proportional to thecurrent point size; drivers should continue to 
do this if no Dt command has been given or if a Dt command has been given with a 
negative value of n. A zero valueof n selects the smallest available linethickness. 

A difficulty arises in how thecurrent position should be changed after the execution of these commands. This is not of great 
importance because the code generated by GN U pic does not depend on this. Given a drawing command of the form 

\Dc xl yl x2 y2 ... xn yn 

where c is not one of c, e, I, a, or ~, U NIX troff will treat each of thex as a horizontal quantity and each of they i as a 
vertical quantity and will assume that the width of the drawn object isIXxi and that the height is XX yi. (The 
assumption about the height can be seen by examining the stand sb registers after using such a D command in a\w escape 
sequence.) This rule also holds for all the original drawing commands with the exception of De. For the sake of compatibil¬ 
ity, GNU troff also follows this rule, even though it produces an ugly result in the case of the Df, Dt, and, to a lesser extent, 
DE commands. Thus after executing a D command of the form 
Dc xl y1 x2 y2 ... xn yn\n 

thecurrent position should be increased by (XX xi; XX yi). 

A continuation convention permits the argument to thex X command to contain newlines: when outputting the argument 
to thex X command, GNU trotf will follow each newline in the argument with a + character (as usual, it will terminate the 
entire argument with a newline); thus if the line after the line containing the x X command starts with +, then the newline 
ending the line containing thex X command should be treated as part of the argument to thex X command, the + should be 
ignored, and the part of the line following the + should be treated I ike the part of the line following thex X command. 
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SEE ALSO 

groff_font(5) 
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group— User group file. 

DESCRIPTION 

/etc/group is an ASCII file that defines the groups to which users belong. There is one entry per line, and each line has the 
format 

group name :passwd :GI D:user_l i st 

Thefield descriptions are 

group, name T he name of the group. 

pas s wd The (encrypted) group password. If thisfield isempty, no password isneeded. 

gid The numerical group ID. 

user .1 i st All thegroup member's usernames, separated by commas. 

FILES 

/etc/ group 

SEE ALSO 

login(l), newgrp(l), passwd(5) 

Linux, 29 December 1992 
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history— Record of current and recently expired U senet articles. 

DESCRIPTION 

The file /news/iib/history keeps a record of all articles currently stored in the news system, as well as those that have been 
received but since expired. 

The file consists of text lines. Each line corresponds to one article The file is normally kept sorted in the order in which 
articles are received, although this is not a requirement. innd(8) appends a new line each time it files an article, and expire(8) 
builds a new version of the file by removing old articles and purging old entries. 

Each line consists of two or three fields separated by a tab, shown below as\t: 

<Mes sage-1 D>\t dat e 

<Me s s a g e -1 D>\t date \t f i I es 

T he Mes s a ge- 1 d field isthe value of the article's M essage-ID header, including the angle brackets. 

The date field consists of three subfields separated by a tilde. All subfields are the text representation of the number of 
seconds si nee the epoch— atime_t; seegettimeotday(2). Thefirst subfield isthe article's arrival date. If copies of the article 
are still present, then the second subfield is either the value of the article's Expires header ora hyphen if no expiration date 
was specified. If an article has been expired, the second subfield will be a hyphen. The third subfield is the value of the 
article's Date header, recordingwhen the article was posted. 
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T hef i i es field is a set of entries separated by one or more spaces. Each entry consists of the name of the newsgroup, a slash, 
and the article number. T hisfield isempty if the article has been expi red. 

For example, an article cross-posted to comp.sources, unix and comp.sources, d that was posted on February 10,1991, (and 
received three minutes later) with an expiration date of M ay 5,1991, could have a history line (broken into two lines for 
display) likethefollowing: 

<312@litchi.f 00 .com> \t 666162000~673329600"666162180 
\t comp.sources.unix/1104 comp.sources.d/7056 

In addition to the text file, thereisadbz(3z) database associated with the file that uses the M essage-ID field as a key to 
determine the offset in the text file where the associated line begins. For historical reasons, the key includes the trailing \0 
byte(which is not stored in thetextfile). 

HISTORY 

W ritten by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

dbz(3z), expire®, innd(8), news-recovery® 

hosts.nntp, hosts.nntp.nolimit 

hosts.nntp, hosts, nntp. noiimit — List of hosts that feed N NTP news. 

DESCRIPTION 

The file /news/iib/hosts.nntp is read by mnd(8) to get the list of hosts that feed the local site Usenet news using the N NTP 
protocol. The server reads this file at startup or when directed to by ctiinnd(8). When a hosts connects to the N NTP port of 
the system on which innd is running, the server will do a check to see if their Internet address is the same as one of the hosts 
named in thisfile. If the host is not mentioned, then innd will spawn an nnrpd(8) to process the connection, with the 
accepted connection on standard input and standard output. 

Comments begin with a number sign (#) and continue through the end of the line. Blank lines and comments are also 
ignored. All other lines should consist of two or three fields separated by acolon. 

Thefirst field should be either an Internet addressin dotted-quad format or an address that can be parsed by 
gethostbyname(3). If a host's entry has multiple addresses, all of them will be added to the access list. The second field, which 
may be blank, isthepassword theforeign host isrequired to usewhen first connecting. The third field, which may be 
omitted, isa list of newsgroups to which the host may post articles. T his list is parsed asanewsfeeds(5) subscription list; 
groups not in the list are ignored. 

Because innd is usually started at system boot time, the local nameserver may not be fully operational when innd parses this 
file. As a work-around, a ctiinnd reload command can be performed after a delay of an hour or so. It is also possible to 
provide both a host's name and its dotted-quad addressin thefile 

For example: 

## FOO has a password, UUNET doesn't. 

## UUNET cannot post to local groups. 

## These are comment lines. 
news.foo.com:magic 
uunet.uu.net::!foo.* 

If the file contains passwords it should not beworld-readable. The file/news/iib/hosts. nntp. noiimit, if it exists, is read 
whenever the hosts, nntp file is read. It has the same format, although only thefirst field is used. Any host mentioned in this 
file is not subject to the incoming connections limit specified by innd's-c flag. This can be used to allow local hosts or time- 
sensitive peers to connect regardless of the local conditions. 
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HISTORY 

W ritten by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

ctlinnd(8), innd(8), nnrpd(8) 

hosts_access 

hosts_access— Format of host access control files. 

DESCRIPTION 

This manual page describes a simple access control language that is based on client (hostnam^address, username) and server 
(process name) patterns. Examples are given at the end. The impatient reader can skip to the "Examples'' section for a quick 
introduction. 

In the foil owing text, daemon is the process name of a network daemon process, and client is the name or address of a host 
requesting service. N etwork daemon process names are specified i n the inetd configuration file. 

ACCESS CONTROL FILES 

The access control software consults two files. The search stops at the first match: 

Access will be granted when a (daemon.c i i ent ) pair matches an entry in the /etc/hosts, allow file 
Otherwise, access will be denied when a (daemon ,ci i ent ) pair matches an entry in the /etc/hosts, deny file. 

Otherwise, access will be granted. 

A non-existing access control file is treated as if it were an empty file Thus, access control can be turned off by providing no 
access control files. 

ACCESS CONTROL RULES 

Each access control file consists of zero or more lines of text. These lines are processed in order of appearance. The search 
terminates when a match is found. 

A newline character is ignored when it is preceded by a backslash character. 

Blank lines or lines that begin with a# character are ignored. 

All other lines should satisfy the following format, things between n being optional: 

daemon_l i st : cl i ent_i i st [ : sheI I _command ] 

daemonjist is a list of one or more daemon process names (argv[ 0 ] values) or wildcards. 

ci i ent j i st is a list of one or more hostnames, host addresses, patterns, or wildcards that will be matched against the remote 
hostname or address. 

List elements should be separated by blanks or commas. 

With the exception of N IS (YP) netgroup lookups, all access control checks are case insensitive. 

PATTERNS 

T he access control language implements the following patterns: 

A string that begins with a . character: A client name or address is matched if its last components match the specified 
pattern. For example, the pattern .tue.m matchesthehostnamewzv.win.tue.nl. 

A string that ends with a . character: A client name or address is matched if its first fields match the given string. For 
example, the pattern 131.155. matches the address of (almost) every host on theEindhoven University network 

(131. 155 .x .x). 
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A string that begins with a® character is treated as a netgroup name N etgroups are usually supported on systems with N IS 
(formerlyYP) databases. A client hostname is matched if itisa(host) member of the specified netgroup. 

An expression of the form n .n .n .n/m.m.m.m is interpreted as a net/mask pair. A client address is matched if net is equal to the 
bitwise and of the address and themask. For example, the net / mask pattern 131.155.72.0/255.255.254.0 matches every address 
in the range 131.155.72.0 through 131.155.73.255. 


WILDCARDS 

The access control language supports explicit wildcards: 

all If thistoken appears in a daemon list, it matches all network daemon process names. I f the all 

token appearsin a client list, itmatchesall client names and addresses. 
local M atchesany string that does not contain a dot character. Typical use is in client lists. 

unknown M atches any host whose name or address are unknown. Should be used with care: H ostnames 

may be unavailable due to temporary nameserver problems. A network address will be 
unavai I able when the software cannot figure out what type of network it is talking to. 
known M atches any host whose name and address are known. Should be used with care: H ostnames 

may be unavailable due to temporary nameserver problems. A network address will be 
unavailable when the software cannot figure out what type of network it is talking to. 
fail Like the all wildcard but causes the software to pretend that the scan of the current access 

control table fails, fail isbeing phased out; itwill become an undocumented feature. The 
except operator is a much cleaner alternative. 


OPERATORS 

except Intended useisof theform: 1 i st 1 except i i s t _ 2 ; thisconstruct matches anything that 

matchesi i st_i unlessitmatchesi i s t _ 2 . T his construct can beused in daemon lists and in 
client lists. The except operator can be nested: If the control language would permit theuse 
of parentheses, a except b except c would parse as (a except (b except c». 


SHELLCOMMANDS 

If the first-matched access control rule contains a shell command, that command is subjected to the following substitutions: 
%a Expands to the remote host address. 

%c Expands to client information: user@host, user@address, a hostname, or just an address, 

depending on how much information is available. 

%h Expands to the remote hostname (or address, if the hostname is unavailable). 

%d Expands to the daemon process name (argv[ 0 ] value). 

%p Expands to the daemon process ID. 

%u Expands to the remote username (or unknown). 

%% Expands to a single % character. 

Characters in % expansions that may confuse the shell are replaced by underscores. The result is executed by a /bin/sh child 
process with standard input, output, and error connected to /dev/nun. Specify an & at the end of the command if you do not 
want to wait until it has completed. 

Shell commands should not rely on the path setting of themetd. Instead, they should use absolute pathnames, or they 
should begin with an explicit PATH=whatever statement. 

REMOTE USERNAME LOOKUP 

When the client host supports the RFC 931 protocol or one of its descendants (tap, ident) the wrapper programs can 
retrieve additional information about the owner of a connection. When available, remote username information is logged 
together with the client hostname and can beused to match patterns like 

daemon l i st : ... user_pattern@host_pattern ... 
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Thedaemon wrappers can be configured at compile time to perform rule-driven username lookups (default) or to always 
interrogate the client host. In thecaseof rule-driven username lookups, the preceding rulewould cause username lookup 
only when both thedaemonj i st and thehos t _ pat t er n match. 

A user pattern has the same syntax as a daemon process name, hostname or host address pattern, so the same wildcards and 
so on apply (but netgroup membership of users is not supported). One should not get carried away with username lookups 
however. 

The remote username information cannot be trusted when it is needed most—that is, when the remote system has been 
compromised. In general, all and (un)known are the only username patterns that make sense. 

Username lookups are possible only with TCP-based services and only when the client host runs a suitable daemon; in all 
other cases the result is unknown. 

A well-known UNIX kernel bug may cause loss of service when username lookups are blocked by a firewall. Thewrapper 
readme document describes a procedure to find out if your kernel has this bug. 

Username lookups cause noticeable delays for PC users.ThedefauIttime-outforusernamelookupsisten seconds: too short 
to copewith slow networks but long enough to irritate PC users. 

Selective username lookups can alleviate the last problem. For example a rulelike 
daemonjist : @pcnetgroup ALL@ALL 

would match members of thepcnetgroup without doing username lookups but would perform username lookups with all 
other systems. 

EXAMPLES 

The language is flexi ble enough that different types of access control policy can be expressed with aminimum of fuss. 
Although the language uses two access control tables, the most common policies can be implemented with one of the tables 
being trivial or a/en empty. 

When reading the following examples it is important to realize that the allow table is scanned before the deny table that the 
search terminates when a match is found, and that access is granted when no match is found at all. 

The exam pies use host and domain names. T hey can be improved by includi ng address or network/netmask information to 
reduce the impact of temporary nameserver lookup failures. 

MOSTLY CLOSED 

In thiscase, access is denied by default. Only explicitly authorized hosts are permitted access. 

The default policy (no access) is implemented with a trivial deny file: 

/etc/hosts.deny: 

ALL: ALL 

This denies all service to all hosts, unless they are permitted access by entries in the allow file. 

The explicitly authorized hosts are listed in theaiiow file: 

/etc/hosts.allow: 

ALL: LOCAL @some_net group 

ALL: .foobar.edu EXCEPT terninalserver.foobar.edu 

The first rule permits access to all services from hosts in the local domain (no . in the hostname) and from members of the 
so me, net group netgroup. The second rule permits access to all services from all hosts in the .foobar.edu domain, with the 
exception Of tenninalserver.foobar.edu. 

MOSTLY OPEN 

Here, access is granted by default; only explicitly specified hosts are refused service. 
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T he default policy (access granted) makes the allow file redundant so that it can be omitted. T he explicitly non-authorized 
hosts are listed in thedeny file: 

/etc/hosts.deny: 

ALL: some.host.name, .some.domain 

ALL EXCEPT in.fingerd: other.host.name, .other.domain 

Thefirst rule denies some hosts all services; thesecond rule still permits finger requests from other hosts. 

BOO BY TRAPS 

The next example permits tftp requests from hosts in thelocal domain. Requests from anyother hosts are denied. Instead of 
the requested file, a finger probe is sent to the offending host. The result is mailed to the superuser. 

/etc/hosts.allow: 

in.tftpd: LOCAL, .my.domain 
/etc/hosts.deny: 

in.tftpd: ALL: (/some/where/safe_finger -1 @%h | \ 

/usr/ucb/mail -s %d-%h root) & 

T he sat e_f inger command comes with thetcpd wrapper and should deinstalled in a suitable place. It limits possible damage 
from data sent by the remote finger server. It gives better protection than thestandard finger command. 

The expansion of the %h (remote host) and %d (service name) sequences is described in the section on shell commands. 
Warning: Do not booby-trap your finger daemon, unless you are prepared for infinite finger loops. 

On network firewall systems, this trick can be carried even further. The typical network firewall only provides a limited set of 
services to the outer world. All other services can be "bugged" just like the preceding tftp example. The result is an excellent 
early-warning system. 

DIAGNOSTICS 

An error is reported when a syntax error is found in a host access control rule, when the length of an access control rule 
exceeds the capacity of an internal buffer, when an access control rule is not terminated by a newline character, when the 
result of %<char act er> expansion would overflow an internal buffer, and when a system call fails that shouldn't. All problems 
are reported via the sysiog daemon. 

FILES 

/etc/hosts, allow, (daemon,cl i ent ) pairs that are granted access. 

/etc/hosts .deny, (daemon ,c i i ent ) pai rs that are denied access. 

SEE ALSO 

tcpd(8), TCP/IP daemon wrapper program 

BUGS 

If a nameserver lookup times out, the hostname will not be available to the access control software, even though the host is 
registered. 

Domain nameserver lookups are case insensitive; N IS (formerly YP) netgroup lookups are case sensitive. 

AUTHOR 

WietseVenema (wietse@wzv.win.tue.m), Department of M athematicsand Computing Science, Eindhoven University of 
Technology, Den Dolech 2, P.O. Box513, 5600 M B Eindhoven, TheN etherlands. 
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hosts_options 

hosts_options — H ost access control language extensions 

DESCRIPTION 

This document describes optional extensions to the language described in thehosts_access(5) document. The extensions are 
enabled at program build time by editing the makefile 

T he extensible language uses the following format: 

daemonjist : clientjist : option : option ... 

T he first two fields are described in the hosts_access(5) manual page. T he remainder of the rules is a list of zero or more 
options. Any : characters within options should be protected with a backslash. 

An option is of the form keyword or keyword = vai ue. 0 ptions are processed in the specified order. W ith some options, the 
val ue i s su bj ected to %<c ha r ac t er > substitutions. 

OPTIONS 

severity = mail.info C hange the severity level at which theevent will belogged. Facility names (such as 

mail) are optional and are not supported on systems with older sysiog implementa¬ 
tions. The severity option can be used to emphasize or to completely ignore specific 
events. 

allow (deny) Grant (deny) service even when the matched rule was found in the hosts.deny 

(hosts.allow) file. These optionsmust appear at the end of a rule. 

With the allow and deny keywords, it is possible to keep all access control rules within a singlefile—for example, in the 
hosts. allow fi le: 

ALL: .friendly.domain: allow 
ALL: ALL: deny 

This permits access from specific hosts only. On the other hand, 

ALL: .trouble-makers: deny 
ALL: ALL: allow 

This permits access from all hosts except a few troublemakers, 
twist = shell command 


in.ftpd : ... : twist = /bin/echo 421 

in.telnetd : ... : twist = PATH=/some/other; exec in.telnetd 


spawn = shell_command 


Replace the current process by an instance of the 
specified shell command, after performing the 
%<c haracter > expansions described in the 
hosts_access(5) manual page, stdin, stdout, and 
stderr are connected to the remote client process. 
This option must appear at the end of a rule. 
Examples: 

Some bounce message sends a customized bounce 
message to the remote client instead of runningthe 
real FTP daemon. 

Runs /some/other/in.telnetd without polluting its 
command-line array or its process environment. 
Warning: In case of U D P services, do not twist into 
commands that use the standard I/O or the 
read(2)/write(2) routines to communicate with the 
client process; U D P requires other I/O primitives. 
Execute the shell command in a chi Id process, after 
performing the%<c h a r a c t er > expansions descri bed 
in the hosts access(5) manual page. The command 
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spawn = (/some/where/safe_finger -1 @%h j /usr/ucb/mail root) & 


umask = 022 


keepalive 


linger = number_of_seconds 


nice = niceval 
nice (no argument) 


user = nobody 


group = tty 


setenv = name value 


is executed with stdin, stdout, and stderr 
connected to the null device so that it won't mess 
up the conversation with the remote host. Example: 
Executes, in a background child process, theshell 
Command safe_finger -1 @%h ] mail root after 
replaci ng %h by the name or address of the remote 
host. 

T he example uses the sate_finger command 
instead of the regular finger command to limit 
possibledamagefrom data sent by thefinger server. 
T he saf e_f inger command is part of the daemon 
wrapper package; it is a wrapper around the regular 
finger command that filters the data sent by the 
remote host. 

Like the umask command that is built into theshell. 
An umask of @22 prevents the creation of files with 
group and world write permission. The umask 
argument should be an octal number. 

C auses the server to periodically send a message to 
the client. The connection isconsidered broken 
when the client does not respond. The keepalive 
option can be useful when users turn off their 
machine while it is still connected to a server. T he 
keepalive option is not useful for datagram (U D P) 
servi ces. 

Specifies how long the kernel will try to deliver not- 
yet delivered data after the server process closes a 
connection. 

C hange the nice value of the process (default 10 ). 
Specify a positive value to spend more CPU 
resources on other processes. 

Assume the privileges of thenobody account. Thisis 
useful with inetd implementations that run all 
servi ceswith root privilege. It isgood practice to 
run services such as finger at a reduced privilege 
level. 

Assume the privileges of thetty group. Thisis 
useful mostly in combination with the user option. 
In order to switch both user and group IDs, switch 
group ID before switching user ID. 

Place a (name, va 1 ue) pair into the process environ¬ 
ment. The va I ue is subjected to %<c h a r a c t e r > 
expansionsand may contain whitespace (but 
leading and trailing blanks are stripped off). 
Warning: Many network daemons reset their 
environment before spawning a login or shell 
process. 
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rfc931 = ti meouti nseconds 

rfc93i (no argument) Look up the remoteuser namewith the RFC 931 

(ident and so on) protocol. Thisoption issilently 
ignored in case of services based on transports other 
than TCP. It requires that the client system runs an 
RFC 931 (ident and so on) compliant daemon and 
may cause noticeable delays with connectionsfrom 
non-U NIX hosts. The time-out period isoptional. 
If no time-out is specified, a default value is taken. 

DIAGNOSTICS 

When a syntax error is found in an access control rule, the error is reported to thesysiog daemon; further options will be 
ignored, and service is denied. 

SEE ALSO 

hosts_access(5), the default access control language 

AUTHOR 

WietseVenema (wietse@wzv.win.tue.m), Department of M athematicsand Computing Science, Eindhoven University of 
Technology, Den Dolech 2, P.O. Box513, 5600 M B Eindhoven, TheN etherlands. 
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inittab— Format of the inittab fi le used by the SysV-compatible init process. 


DESCRIPTION 

The inittab file describes which processes are started at bootup and during normal operation (such as/etc/rc, gettys). init 
distinguishes multiple run levels, of which each can have its own set of processes that are started. Valid runi evei s are 0-6 and 
a, b, and cfor ondemand entries. An entry in the inittab file has the foil owing format: 

i d:r unI evel s :action:process 


Lines beginning with # are ignored. 


r uni evel s 
acti on 


A uniquetwo-character-sequence which identifies an entry in inittab. 

N ote: For gettys or other login processes, thei d field should be the tty suffix of the 
corresponding tty, such as 1 forttyi. Otherwise, the login accounting will not work 
correctly. This is a bug in login and will be fixed. 

D escri bes in which run levels the specified action should betaken. 

Describes which action should betaken. 


process Specifies the process to be executed. If theprocess field starts with a+ character, init will 

not do utmp and wtmp accounting for that process. This is needed for gettys that insist on 
doing their own utmp/wtmp housekeeping. This is also a historic bug. 


Valid actions are 

respawn 

wait 

once 

boot 


The process will be restarted whenever it terminates (such asgetty). 

Theprocess will be started oncewhen the specified run level isentered and init will wait 
for its termination. 

The process will be executed oncewhen the specified run level isentered. 

The process will be executed during system boot. The run level field is ignored. 
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bootwait 

off 

ondemand 

initdefault 

sysinit 

powerwait 

powerfail 

powerokwait 

ctrlaltdel 


The process will be executed during system boot while init waits for its termination (such 
as/etc/rc). Theruni evei field is ignored. 

This does nothing. 

A process marked with ondemand will be executed whenever the specified ondemand run level 
is called. H owever, no r uni evei change will occur. 

An initdefauit-entry specifies the run level that should be entered after system boot. If 
noneexists, init will ask for a r uni evei on theconsole. 

Theprocesswill be executed during system boot. It will be executed before any boot or 
bootwait entries. 

Theprocesswill be executed when init receives thesiGPWR signal, indicating that there is 
something wrong with the power, init will wait for the process to finish before continuing. 
As powerwait but init will not wait for the processes completion. 

Theprocesswill be executed when init receives thesiGPWR signal, provided there is a file 
called /etc/powerstatus containing the word ok. Thismeansthat the power has come back 
again. 

Theprocesswill be executed when init receivesthe sigint signal. Thismeansthat someone 
on the system console pressed the Ctrl+Alt+D el key combination. Typically, one wants to 
execute some sort of shutdown either to get into single-user level or to reboot the machine. 


Theruni evei field may contain multiple characters for different run levels, such as 123 if the process should be started in run 
levels 1, 2 and 3. ondemand entries may contain an a, b, ore. Theruni evei field of sysinit, boot, and bootwait entries are 
ignored. 

When the run level is changed, any running processes that are not specified for the new run level are killed, first with sigterm 
and then with sigkill. 


EXAMPLES 

This is an example of an inittab that resembles the old Linux inittab: 

# inittab for linux 
id:1:initdefault: 
re:rbootwait:/etc/rc 

1:1:respawn:/etc/getty 9600 tty 1 
2:1:respawn:/etc/getty 9600 tty2 
3:1:respawn:/etc/getty 9600 tty3 
4:1:respawn:/etc/getty 9600 tty4 

Thisinittab file executes /etc/rc during boot and startsgettys on ttyi-tty4. 

A more elaborate inittab with different run levels (see thecommentsinside) is 

#Level to run in 
id:4:initdefault: 
ud::boot:/etc/update 
rc::bootwait:/etc/rc 
cr::boot:/etc/crond 

# 

# level 1: getty on tty1 

# level 2: getty on tty1 -4 

# level 3: tty1 -4, dialin via modem(ttys2) 

# level 4: tty1 -4, ttyb 

# 

mr:126:once:/usr/bin/nodialin 
mi:345:once:/usr/bin/dialin 
1:1234:respawn:/etc/getty 9600 tty1 
2:234:respawn:/etc/getty 9600 tty2 
3:234:respawn:/etc/getty 9600 tty3 
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4:234:respawn:/etc/getty 9600 tty4 
s2:3:respawn:/etc/mgetty ttys2 19200 
b:4:respawn:/etc/getty 19200L ttyb 
ca: :ctrlaltdel:/etc/shutdown -t3 -rf now 

FILES 

/etc/inittab 

AUTHOR 

init was written by M iquel van Smoorenburg (miqueis@drinkei.ni.mugnet.org). The manual page was written by Sebastian 
Lederer (lederer@francium.informatik.uni-bonn.de) and modified by M ichael H aardt (u31b3hs@pool.informatik.rwth- 
aachen.de). 

SEE ALSO 

init(8), telinit(8) 

13 May 1993 
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inn. cont— C onfigurati on data for I nterN etN ews programs. 


DESCRIPTION 

The file /news/iib/inn.conf is used to determine various parameters Blank lines and lines starting with a number sign (#) are 
ignored. All other lines specify parameters that may be read and should be of the following form: 
name : [optional whitespace] value 


Everything after the whitespace and up to the end of the line is taken asthevai ue; multi-word values should not be put in 
quotes. The case of names is significant; server is not the same as server or server. 

Some parameters specified in the file may be overridden by environment variables, and some file parameters may be used to 
mask real data, such as when hiding a cluster of hosts behind a single electronic mail hostname. The current set of parameters 
is as follows: 


fromhost 

moderatormailer 

organization 

pathhost 

server 

domain 


This is the name of the host to use when bui Iding the F rom header line. T he default is the 
fully qualified domain name of the local host. The value of the fromhost environment 
variable, if it exists, overrides this. 

This names the default machine that contains forwarding aliases for all moderated groups. It 
is only used if themoderators(5) file doesn't exist or if the group is not matched by that file 
The value is interpreted as a pattern match; seemoderators(5). 

This specifies what to put in the Organization header if it is blank. The value of the 
organization environment variable if it exists, overrides this 

This specifies how to name the local site when bui Iding the Path header line The default is 
thefully qualified domain name of the local host. 

This specifies the name of theN NTP server to which an article should be posted. The value 
of the nntpserver environment variable, if it exists, overrides this. 

This should be the domain name of the local host. It should not have a leading period, and 
it should notbeafull host address. Itisused only if the GetFQDN routinein iibinn(3) cannot 
get thefully qualified domain name by using either the gethostname(2) orgethostbyname(3) 
calls. The check is very simple; if either routine returns a name with a period in it, then it is 
assumed to havethefull domain name. 
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Three parameters are used only bynnrpd when accepting postingsfrom clients: 

mime-version If this parameter is present, then nnrpd will add the necessary MIME (M ulti purpose Internet 

Mail Extensions) headers to all any articles that do not havea M ime-Version header.This 
parameter specifies the M IM E version and should normally be i . 0 . 
mime-contenttype If M IM E headers are bei ng added, this parameter specifies the value of the Content-Type 

header. The default value istext/piain; charset=us-Ascn. 
mime-encoding If M IM E headers are bei ng added, this parameter specifies the value of the C ontent- 

T ransfer-Encoding header. The default value iS7bit. 

Note that this file can beidentical on all machinesin an organization. 


EXAMPLE 

fromhost: 

moderatormailer: 

organization: 

#pathhost: 

server: 

domain: 


foo.com 

%s@uunet.uu.net 
Foo, Incorporated 
U Se FQDN. 
news.foo.com 
foo.com 


This file is intended to be fairly static; any changes made to it are typically not reflected until a program restarts. 

HISTORY 

W ritten by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

libinn(3), moderators(5) 


innwatch.ctl 

innwatch.cti —Control Usenet supervision by innwatch. 

DESCRIPTION 

The file /news/iib/innwatch.cti is used to determine what actions are taken during the periodic supervisions by innwatch. 

The file consists of a series of lines; blank lines and lines beginning with a number sign (#) are ignored. All other lines consist 
of seven fields, each preceded by a delimiting character: 

:label:state:condition:test:limit:command:reason 

The deli miter can beany one of several non-alphanumeric characters that does not appear elsewhere in the line; there is no 
way to quote it to include it in any of the fields. Any of i, ,, :, e,;, or ? is a good choice. Each line can have a different 
delimiter; the first character on each line is the delimiter for that line. Whitespace surrounding delimiters, except before the 
first, isignored and does not form part of thefields; whitespacewithin fields is permitted. All delimiters must be present. 

The first field is a label for the control line. It is used as an internal state indicator and in ctiinnd messages to control the 
server. If omitted, the line number is used. 

The second field specifies when thiscontrol lineshould beused. It consists of a list of labels and special indicators separated 
by whitespace. If the current state matches against any of the labels in this field, this line will beused as described below. The 
values that may be used are 

T his li ne matches if the current state is the same as the label on this li ne; or if the current state 
is run, the initial state. This is also the default state if this field is empty. 
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+ T his line matches if the current state is run. 

* This line always matches. 

label T his line matches if the current state is the specified i a be i. 

-label This line matches if the current state is not the specified i abei. 

The third field specifies a shell command that is invoked if this line matches. Do not use any shell filename expansion 
characters such as*, ?, or [ (a/en quoted, they're not likely to work as intended). If the command succeeds, as indicated by 
its exit status it is expected to have printed a single integer to standard output. This gives the value of this control line, to be 
used below. If the command fails the line is ignored. The command is executed with its current directory set to the 
newsspool directory, /news/spool. 

The fourth field specifies the operator to use to test the value returned above. It should be one of the two-letter numeric test 
operators defined in test(l) such aseq, it, and the like. The leading dash (-) should not beincluded. 

The fifth field specifies a constant with which to compare the value using the operator just defined. This is done by invoking 
the command 

test value -operator constant 
Thelineissaid to "succeed" if it returns true. 

The sixth field specifies what should be done if the line succeeds and in some cases if it fails. Any of the following words may 
be used: 

throttle Causes mnwatch to throttle the server if thisline succeeds. It also sets the state to thevalueof 

the line's label. If the line fails and the state was previously equal to the label on this line (that 
is, this line had previously succeeded), then ago command will be sent to the server, and 
innwatch will return to the run state. The throttle is only performed if the current state is run 
or a state other than thelabel of thisline, regardless of whether the command succeeds, 
pause Is identical to throttle except that the server is paused, 

shutdown Sends a shutdown command totheserver. It isfor emergency useonly. 

flush Sends a flush command to the server. 

go Causes mnwatch to send ago command to the server and to set the state to run. 

exit C auses innwatch to exit. 

skip The result of the control fileisskipped for the current pass. 

The last field specifies the reason that isused in those ctimnd commandsthat requireone. M ore strictly, it is part of the 
reason; innwatch appends some information to it. In order to enable other sites to recognize the state of the local mnd server, 
thisfield should usually beset to one of several standard values. U seNo space if the server is rejecting articles because of a 
lack of filesystem resources. Useioadav if the server is rejecting articles because of a lack of CPU resources. 

Once innwatch has taken some action as a consequence of its control line it skips the rest of the control file for this pass. If 
the action was to restart the server (that is, issue a go command), then the next pass will commence almost immediately so 
that innwatch can discover any other condition that may mean that the server should be suspended again. 

EXAMPLES 

@@@df .|awk 1 NR==2 {print $4} 1 @lt@10000@throttle@No space 

@@@df -i . |awk 'NR==2 {print $4}'@lt@1000@throttle@No space (inodes) 

The first line causes the server to be throttled if the free space drops below 10000 units (using whatever units df uses) and 
restarted again when free space increases above thethreshold. 

Thesecond linedoes the same for inodes. 

The next three lines act as a group and should appear in the following order. It is easier to explain them, however, if they are 
described from the last up. 
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!load!load hiload!loadavg!It!5!go! 

:hiload:+ load:loadavg:gt:8:throttle:loadav 
/load/+/loadavg/ge/6/pause/loadav 

The final line causes the server to be paused if innwatch is in the run state and the load average rises to, or above, six. The 
state is set to load when this happens. The previous line causes the server to be throttled when innwatch is in the run or load 
state, and the load average rises above eight. The state is set to hiload when this happens. N otethat innwatch can switch the 
server from paused to throttled if the load average rises from below six to between six and seven and then to above eight. The 
first line causes the server to be sent a go command if innwatch is in the load or hiload state and the load average drops below 
five. 

N otethat all three lines assume a mythical command loadavg that is assumed to print the current load average as an integer. 

In more practical circumstances, a pipe of uptime into awk is more likely to be useful. 

BUGS 

T hisfi le must be tailored for each individual site; the sample supplied istruly no more than a sample. Thefileshould be 
ordered so that the more common problems are tested first. 

T he run state is not actually identified by the label with that three letter name, and usi ng it will not work as expected. 

Using an "unusual" character for the delimiter such as (, *, &, ■■, and the like is likely to lead to obscure and hard-to-locate 
bugs. 

HISTORY 

W ritten by (kre@munnani.oz.au) for InterN etN ews. 

SEE ALSO 

innd(8j, ctlinnd(8j, news.dailyfSj 


ipc 

ipc— System V interprocess communication mechanisms. 

SYNOPSIS 

# include <sys/types.h> 

# include <sys/ipc.h> 

# include <sys/msg.h> 

# include <sys/sem.h> 

# include <sys/shm.h> 

DESCRIPTION 

The manual page refers to theLinux implementation of theSystem V interprocess communication mechanisms message 
queues, semaphore sets, and shared memory segments. In thefollowing, theword resource meansan instantiation of one 
among such mechanisms. 

RESOURCE ACCESS PERMISSIONS 

For each resource, thesystem uses a common structure of type struct ipc_perm to store information needed in determining 
permissions to perform an ipc operation. Theipc_perm structure, defined by the<sys/ipc.h> system header file, includes the 
following members: 

ushort cuid; /* creator user id */ 
ushort cgid; /* creator group id */ 
ushort uid; /* owner user id */ 
ushort gid; /* owner group id */ 
ushort mode; /* r/w permissions */ 



ipc 



The mode member of theipc_perm structure defines, with its lower nine bits, the access permissions to the resource for a 
process executing an ipc system call. The permissions are interpreted as follows: 


0400 

Read by user. 

0200 

W rite by user. 

0040 

Read by group. 

0020 

W rite by group. 

0004 

Read by others. 

0002 

W rite by others. 


Bits 0100, 0010, and 0001 (the execute bits) are unused by the system. Furthermore "write" effectively means "alter" for a 
semaphore set. 

The same system header file defines also the following symbolic constants: 


IPC_CREAT 

C reate entry if key doesn't exists. 

IPC_EXCL 

Fail if key exists. 

IPC_NOWAIT 

Error if request must wait. 

IPC_PRIVATE 

Private key. 

IPC_RMID 

Remove resource 

IPC_SET 

Set resource options. 

IPC_STAT 

Get resource options. 


N otethat ipc_private is a key_t type whereas all the others symbolic constants are flag fields ORable into an int type 
variable. 


MESSAGE QUEUES 

A message queue is uniquely identified by a positive integer (itsmsqid) and has an associated data structure of type struct 
msquid_ds, defined in <sys/msg.h>, containingthefollowing members: 

struct ipc_perm msg_perm; 
ushort msg_qnum; /* no of messages on queue */ 
ushort msg_qbytes; /* bytes max on a queue */ 
ushort msglspid; /* pid of last msgsnd call */ 

ushort msglrpid; /* pid of last msgrcv call */ 

time_t msg_stime; /* last msgsnd time */ 

time_t msg_rtime; /* last msgrcv time */ 

time_t msg_ctime; /* last change time */ 


msg_perm 

msg_qnum 

msg_qbytes 

msg_lspid 

msg_lrpid 

msg_stime 

msg_rtime 

msg_ctime 


ipc_perm structure that specifies the access permissions on the message queue. 
N umber of messages currently on the message queue. 

M aximum number of bytes of message text allowed on the message queue. 

ID of the process that performed the last msgsnd system call. 

ID of the process that performed the last msgrcv system call. 

Time of the last msgsnd system call. 

T ime of the last msgcv system call. 

Time of the last system call that changed a member of themsqid_ds structure. 


SEMAPHORE SETS 

A semaphore set is uniquely identified by a positive integer (its semid) and has an associated data structure of type struct 
semid_ds, defined in <sys/sem.h>, containing thefollowing members: 

struct ipc_perm sem_perm; 

time_t sem_otime; /* last operation time */ 
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time_t sem_ctime; /* last change time */ 
ushort sem_nsems; /* count of sems in set */ 

sem_perm ipc_perm structure that specifies the access permissions on the semaphore set. 

sem_otime Time of last semop system call. 

sem_ctime Timeof last semcti system call that changed a member of the above structure or of one 

semaphore belongi ng to the set. 

sem_nsems N umber of semaphores in the set. Each semaphore of the set is referenced by a non-negative 

integer ranging from 0 to sem_nsems-i. 

A semaphore is a data structure of type struct sen containing the following members: 

ushort semval; /* semaphore value */ 
short sempid; /* pid for last operation */ 
ushort semncnt; /* no. of awaiting semval to increase */ 
ushort semzcnt; /* no. of awaiting semval = 0 */ 

semval Semaphore value a non-negative integer. 

sempid ID of the last process that performed a semaphore operation on this semaphore, 

semncnt N umber of processes suspended awaiting for semval to increase, 

semznt N umber of processes suspended awaiting for semval to become zero. 


SHARED MEMORY SEGMENTS 

A shared memory segment is uniquely identified by a positive integer (its shmid) and has an associated data structure of type 
struct shmid ds, defined in <sys/shm.h>, containingthefollowing members: 

struct ipc_perm shm_perm; 
int shm_segsz; /* size of segment */ 
ushort shm_cpid; /* pid of creator */ 
ushort shm_lpid; /* pid, last operation */ 
short shm_nattch; /* no. of current attaches */ 

time_t shm_atime; /* time of last attach */ 

time_t shm_dtime; /* time of last detach */ 

time_t shm_ctime; /* time of last change */ 


shm_perm 

shm_segsz 

shm_cpid 

shm_lpid 

shm_nattch 

shm_atime 

shm_dtime 

shm_ctime 


ipc_perm structure that specifies the access permissions on the shared memory segment. 
Size in bytes of the shared memory segment. 

ID of the process that created the shared memory segment. 

ID of the last process that executed ashmat orshmdt system call. 

N umber of current alive attaches for this shared memory segment. 

Timeof the last shmat system call. 

Timeof the last shmdt system call. 

Timeof the last shmcti system call that changed shmidds. 


SEE ALSO 

ftok(3), msgctl(2), msgget(2), msgrcv(2), msgsnd(2), semctl(2), semget(2), semop(2), shmat(2), shmctl(2), shmget(2), shmdt (2) 

Linux 0.99.13,1 N ovember 1993 


issue 


issue— Issue identification file. 
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DESCRIPTION 

Thefile /etc/issue is a text file that containsa message or system identification to be printed before the login prompt. It 
may contain variousuchar and \c har sequences if supported by getty(l). 

FILES 

/etc/issue 

SEE ALSO 

getty(l), motd(5) 

Linux, 24July 1993 


lilo.conf 

liio.cont— Configuration file for LILO. 

DESCRIPTION 

Thisfile, by default /etc/iiio.conf, isread by theboot loader installer LILO (see iiio(8)). 

It might look as follows: 

boot = /dev/hda 

delay = 40 

compact 

vga = normal 

root = /dev/hdal 

read-only 

image = /zlmage-1.5.99 
label = try 
image = /zlmage-1.0.9 
label = 1.0.9 
image = /tamu/vmlinuz 
label = tamu 
root = /dev/hdb2 
vga = ask 
other = /dev/hda3 
label = dos 
table = /dev/hda 

This configuration file specifies that LILO uses the M aster Boot Record on /dev/hda. (For a discussion of the various ways to 
use LILO and the interaction with other operating systems, seeuser.tex from the LILO documentation.) 

When booting, theboot loader will wait 4 seconds (40 deciseconds) for you to press Shift. If you don't, then the first kernel 
image mentioned (/zimage- 1 . 5 . 99 , which you probably installed just 5 minutes ago) will be booted. If you do, theboot 
loader will ask you which image to boot. In case you forgot the possible choices, press Tab (or ? if you have a U .5. keyboard), 
and you will be presented with a menu. You now have the choice of booting this brand new kernel, an old trusted kernel, or 
a kernel on another root file system (just in case you did something stupid on your usual root) or booting a different 
operating system. There can be up to 16 images mentioned in nio.oonf. 

As can be seen previously, a configuration file starts with a number of global options (the top six lines in the example), 
followed by descriptions of theoptionsforthevariousimages. An option in an image description will override a global 
option. 
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GLOBAL OPTIONS 


There are many possible keywords. The description that follows is almost literally from user.tex (just slightly abbreviated): 


backup=b a c k u p - file 
boot=boot-devi ce 

compact 

default=name 

delay=t secs 

disk=devi ce- name 

disktab=di sktab-fiI e 

fix-table 


force -backup=b a c k u p-fiI e 
ignore-table 
install=boot- sector 

linear 


lock 

map=map- file 
message=mes sage-file 


nowarn 


Copy the original boot sector to backup-f i i e (which may also be a device, such as /dev/nuii) 
instead of /boot/boot. nnnn. 

Sets the name of the device (such as a hard disk partition) that contains the boot sector. If 
this keyword is omitted, the boot sector is read from (and possibly written to) the device 
that is currently mounted as root. 

Triesto merge read requests for adjacent sectors into a single read request. T his drastically 
reducesload time and keepsthe map smaller. Using compact isespeci ally recommended 
when booting from a floppy disk. 

Uses the specified image asthedefault boot image. If default isomitted, theimage 
appearing first in theconfiguration fileisused. 

Specifies the number of tenths of a second the boot loader should wait before booting the 
first image. This is useful on systemsthat immediately boot from the hard disk after 
enabling the keyboard. The boot loader doesn't wait if delay isomitted or is set to zero. 
Defines non-standard parameters for the specified disk. See section "D isk Geometry" of 
user.tex for details 

Specifies the name of the disk parameter table The map installer looks for /etc/disktab if 
disktab is omitted. T he use of disktabs is discouraged. 

This allows LILO to adjust 3-D addresses in partition tables. Each partition entry contains a 
3-D (sector/head/cylinder) and a linear address of the first and the last sector of the 
partition. If a partition is not track-aligned and if certain other operating systems (such as 
PC/M S-DOS or OS/2) are using the same disk, they may change the 3-D address. LILO 
can store its boot sector only on partitions where both address types correspond. LILO 
readjusts incorrect 3-D start addresses if fix-table isset. 

W arning: This does not guarantee that other operating systems may not attempt to reset the 
address later. It isalso possible that this change has other, unexpected side effects. The 
correct fix is to repartition the drive with a program that does align partitions to tracks 
Also, with somedisks(such as some large El DE diskswith address translation enabled), 
under some circumstances, it may even be unavoidable to have conflicting partition table 
entries. 

Like backup but overwrite an old backup copy if it exists. 

Tells LILO to ignore corrupt partition tables. 

Install the specified fileasthenew bootsector. If install isomitted, /boot/boot.b isused as 
the default. 

Generate linear sector addresses instead of sector/head/cylinder addresses. Linear addresses 
are translated at runtime and do not depend on disk geometry. N otethat boot disks may 
not be portable if linear isused because the BIOS service to determine the disk geometry 
does not work reliably for floppy disks. When using linear with large disks, /sbin/iiio may 
generate references to inaccessible disk areas because 3-D sector addresses are not known 
before boot ti me. 

E nables automatic recordi ng of boot command li nes as the defaults for the followi ng boots. 
Thisway, LILO "locks” on achoiceuntil it is manually overridden. 

Specifies the location of the map file If map isomitted, the file /boot/map isused. 

Specifies a fi le containing a message that isdisplayed before the boot prompt. N o messageis 
displayed while waiting for a shifting key after printing lilo . In the message, the ff 
character (Ctrl+L) clears the local screen. T he size of the message file is limited to 65,535 
bytes. The map file has to be rebuilt if the message file is changed or moved. 

D i sables warnings about possiblefutu re dangers. 
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optional 

password=pa s sword 
prompt 

restricted 
serial=pa r a met er s 


timeout=tsecs 


verbose=! e v e I 


T he per-image option optional applies to all images. 

The per-image option password^.. applies to all images. 

Forces entering the boot prompt without expecting any prior key presses. U nattended 
reboots are impossible if prompt is set and timeout isn't. 

The per-image option restricted applies to all images. 

Enables control from aserial line. The specified serial port isinitialized and the bootloader 
is accepting input from it and from the PC's keyboard. Sending a break on the serial line 
corresponds to pressing a Shift key on the console in order to get the boot loader's 
attention. All boot images should be password-protected if the serial access is less secure 
than access to the console, such as if the line is connected to a modem. The parameter string 
has thefollowing syntax: 

<port >[,<bps>[<pari t y>[<bi ts>]]] 

<port >: The number of the serial port, zero-based. 0 corresponds to COM 1 alias /dev/ttyso, 
and so on. All four ports can be used (if present). <bps>: The baud rate of the serial port. 
Thefollowing baud rates are supported: 110,150, 300, 600,1200, 2400, 4800, and 9600 
bps. Default is2400 bps. 

<pari ty>: The parity used on the serial line. The boot loader ignores input parity and strips 
the eighth bit. The following (uppercase or lowercase) characters are used to describe the 
parity: n for no parity, e for even parity, and 0 for odd parity. 

<bi ts>: The number of bits in a character. Only 7 and 8 bits are supported. Default is 8 if 
parity is none and 7 if parity is even or odd. 

If serial isset, the value of delay is automatically raised to 20 . For example seriai= 0 , 2400 ns 
initializes COM 1 with the default parameters. 

Sets a timeout (in tenths of a second) for keyboard input. If no key is pressed for the 
specified time, thefirst image is automatically booted. Similarly, password input isaborted 
if the user isidlefortoo long. The default timeout isinfinite. 

T urns on a lot of progress reporting. FI igher numbers give more verbose output. If -v is 
additionally specified on the LI LO command line, the level is increased accordingly. The 
maximum verbosity I e/el iss. 


Additionally, the kernel configuration parameters append, ramdisk, read-only, read-write, root, and vga can beset in the 
global options section. They are used as defaults if they aren't specified in the configuration sections of the respective kernel 
images. 


PER-IMAGE SECTION 

A per-image section starts with either a line 
image=pat h n a me 

to indicate a file or device containing the boot image of a Linux kernel or a line 
other=pat hna me 

to indicate an arbitrary system to boot. 

In the former case, if an image line specifies booting from adevice then one has to indicate therangeof sectors to be mapped 
using 

range=st art -end 

In the latter case (booting an other system), there are thethree options: 

loaders ha i n- 1 oader This specifies the chain loader that should be used. By default, /boot/chain, b is used. The 

chain loader must be specified if booting from a device other than thefirst hard or floppy 
disk. 
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tabie=devi c e This specifies the device that contai ns the partition table. The boot loader will not pass 

partition information to the booted operating system if this variable is omitted. (Some 
operating systems have other means to determine from which partition they have been 
booted. For example, M S-D OS usually stores the geometry of the boot disk or partition in 
its boot sector.) N otethat /sbin/uio must be rerun if a partition table mapped referenced 
with table ismodified. 

unsafe Do not access the boot sector at map creation time This disables some sanity checks 

including a partition table check. If the boot sector is on a fixed-format floppy disk device, 
using unsafe avoids the need to put a readable disk into the drive when running the map 
installer, unsafe and table are mutually incompatible 


In both cases, the following options apply: 


label=na me 

alias=na me 
lock 

optional 

password=passwor d 
restricted 


The boot loader uses the main filename (without its path) of each image specification to 
identify that image. A different name can be used by setting the variable label. 

A second name for the same entry can beused by specifying an alias. 

(See previous description.) 

Omit the image if it is not available at map creation time. This is useful to specify test 
kernels that are not always present. 

P rotect th e i m age by a passwo rd. 

A password isonly required to boot the image if parameters are specified on thecommand 
line (SUCh as single). 


KERN EL OPTIONS 


If the booted image is a Linux kernel, then one may pass command-line parameters to this kernel. 


append=st ring 


literal=st ri ng 


ramdisk=si z e 


read-only 


read-write 
root=r oot-devi ce 


vga=mode 


Appends the options specified to the parameter line passed to the kernel. This is typically 
used to specify parameters of hardware that can't be entirely autodetected or for which 
probing may be dangerous. Example append = "hd=64, 32 , 202 “. 

Like append but removes all other options (such as setting of the root device). Because vital 
optionscan be removed unintentionally with literal, thisoption cannot be set in the 
global options section. 

This specifies the size of the optional RAM disk. A value of zero indicates that no RAM disk 
should be created. If this variable is omitted, the RAM disk size configured into the boot 
image is used. 

This specifies that the root filesystem should be mounted read-only. Typically, the system 
startup procedure remounts the root filesystem read-write later (such as after fscki ng it). 
This specifies that the root filesystem should be mounted read-write. 

This specifies the device that should be mounted as root. If thespecial namecurrent isused, 
the root device is set to the device on which the root filesystem is currently mounted. If the 
root has been changed with -r, the respective device is used. If the variable root is omitted, 
the root device setting contained inthe kernel imageisused. (That is set at compiletime 
using theraoT dev variablein the kernel makefileand can later be changed with the rdev(8) 
program.) 

T his specifies the VGA text mode that should be selected when booting. The following 

values are recognized (case is ignored): 

normal: Select normal 80x25 text mode. 

extended (or ext): Select 80x50 text mode. 

ask: Stop and ask for user input (at boot time). 

<number >: U se the correspondi ng text mode. A list of available modes can be obtained by 
bootingwith vga=ask and pressing Enter. 



moderators 



If this variable is omitted, theVGA mode setting contained in the kernel imageisused. 
(That is set at compile time using the svga mode variable in the kernel makefile and can later 
be changed with the rdev(8) program.) 


SEE ALSO 

iiio(8), rdev(8). T he LILO distribution comes with very extensive documentation of which the preceding information isan 
extract. 

28 July 1995 


MAKEDEV.cfg 

MAKEDEv.ctg— Configuration forMAKEDEv(8). 

DESCRIPTION 

MAKEDEv.ctg is a text filethat tells makedev(8 ) what to do (and equally importantly, what not to do). U nlike devinfo(5), which 
ismeantto be centrally maintained, it contains all local configuration for a particular site and all customization. There are 
basically two kinds of declaration in this file a "class" declaration and an "omit" declaration. 

A class declaration has the form 

class name : owner group-owner permissions 

This says that any devices placed in the specified class by devinfo should be created with this ownership and these permis¬ 
sions. A sample entry might be 
class public: root system 0666 

This says that devices marked public should be owned by root.system and have mode 666 . 

An omit declaration hastheform 
omit { device... } 

This causes the specified devices to never be created, even if explicitly specified. Use caution when setting this up. The intent 
is to be able to run makedev update and not have it create all sorts of useless devices you'd never use. 

SEE ALSO 

makedev(8), devinfo(5) 

Verson 1.4, January 1995 


moderators 

moderators— M ai I addresses for moderated U senet newsgroups. 

DESCRIPTION 

The GetModeratorAddress(3) routine reads thefile /news/iib/moderators to determine how to reach the moderator of a 
newsgroup. This is used by inews(l) when an unapproved local posting is made to a moderated newsgroup. 

Thefile is read until a match is found. Blank lines and lines starting with a number sign (#) are ignored. All other lines 
should consist of two fields separated by a colon. 

The first field is a wiidmat(3)-style pattern. If it matches the name of the newsgroup, then the second field is taken to be a 
format string for sprmtf (3). This string should have at most one%s parameter, which will be given the name of the 
newsgroup with periods transliterated to dashes. 
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Hereisasamplefile 

foo.important:announce -request@foo.com 
foo.*:%s@mailer.foo.com 
gnu.*:%s@prep.ai.mit.edu 
:%s@uunet.uu.net 

Using thisfile, postings to the moderated newsgroup in the left column will be sent to the address shown in theright 
column: 

f oo. important announce - requests oo .com 
foo.x.announce too -x-announce@mailer.foo.com 
gnu.emacs.sources gnu-emacs-sources@prep.ai.mit.edu 
comp.sources.unix comp-sources-unix@uunet.uu.net 

HISTORY 

W ritten by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

inews(l), inn.conf(5), libinn(3), wildmat(3) 

/etc/modules 

/etc/moduies— Kernel modules to load at boot time. 

DESCRIPTION 

The /etc/moduies file contains the names of kernel modules that are to be loaded at boot time, one per line. Comments 
begin with a#, and everything on the line after them are ignored. 

Debian GNU/Linux version 0.93 


motd 

motd— M essage of the day. 

DESCRIPTION 

The contents of /etc/motd are displayed by iogin(l) after a successful login but just before it executes the login shell. 

The motd stands for "message of the day," and thisfile has been traditionally been used for exactly that. (It requires much less 
disk space than mail to all users.) 

FILES 

/etc/motd 

SEE ALSO 

login(l) issue(5) 

Linux, 29 December 1992 
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mtoois— Table of DOS devices. 
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DESCRIPTION 

/etc/mtoois.conf and -/.mtooisnc are the configuration filesfor mtools. These configuration files describe the following 
items: 

Global configuration flags and variables 
Per-driveflags and variables 
C haracter translation tables 

/etc/mtoois.conf is the system-wide configuration file, and -/.mtooisrc is the user's private configuration file. 

GENERAL SYNTAX 

The configuration files is made up of sections. Each section starts with akeyword identifying the section followed byacolon. 
Then follow variable assignments and flags. Variable assignments take the following form: 

n a me =v a I ue 

Flags are lone keywords without an equal sign and value following them. A section either ends at the end of the file or where 
the next section begins. 

Lines starting with a hash (#) are comments. N ewline characters are equivalent to whitespace (except where ending a 
comment). The configuration file is case insensitive, except for items enclosed in quotes (such as filenames). 

DEFAULT VALUES 

For most platforms, mtools contains reasonable compiled-in defaults. You usually don't need to bother with the configura¬ 
tion file, if all you want to do with mtools is access your floppy drives. On the other hand, the configuration file is needed if 
you also want to use mtools to access your hard disk partitions and dosemu image files. 

GLOBAL VARIABLES 

G lobal variables may be set to i or to 0 . 

Thefollowing global flags are recognized: 

mtools_skip_check If this is set to 1 , mtools skipsmost of its sanity checks. Thisis needed to read someAtari 

disks that have been made with the earlier ROM sand that would not be recognized 
otherwise. 

mtools_fat_compat i b i lity If this is set to i, mtools skips the FAT size checks. Some disks have a bigger FAT than they 

really need. These are rqected ifthisoption isnotset. 

mtools_lower_case If this is set to i, mtools displays all-uppercase short fi lenames as lowercase. This has been 

doneto allow a behavior that is consistent with older versions of mtools, which didn't know 
about the case bits. 

For example, inserting the following line into your configuration file instructs mtools to skip the sanity checks: 

MTOOLS_SKIP_CHECK=1. 

Global variables may also beset via the environment: export mtools_skip_check=i. 

PER-DRIVE FLAG SAND VARIABLES 

Per-drive flags and values may be described in a drive section. A drive section starts with drive driveletter 
Then follow variable-value pairs and flags. 

GENERAL PURPOSE DRIVE VARIABLES 

T he foil owing variables are available: 

tile The name of the file or device holding the disk image. This is mandatory. The filename 

should be enclosed in quotes. 
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If this is set to a nonzero value, mtoois also tries to access this disk as an Xdf disk. Xdf is a 
high-capacity format used by OS/2. This is off by default. 

T el Is mtoois to treat the drive as a partitioned device and to use the given partition. Only 
primary partitionsareaccessible using this method, and they are numbered from lto 4. For 
logical partitions use the more general offset variable. The partition variable is intended 
for Syquests, ZIP drives, and DOSE M U hdi mages. It is not recommended for hard disks to 
which di rect access to partitions is available. 

Describes where in the file the M S-D OS filesystem starts. This is useful for logical partitions 
inDOSEMU hdimages and for AT ARI RAM disks. By default, thisiszero, meaningthat 
the filesystem starts right at the beginning of the device or file. 

The number of FAT bits. This can be 12 or 1 6. This is very rarely needed because it can 
almost always be deduced from information in the boot sector. On the contrary, describing 
the number of fat bits can actually be harmful if you get it wrong. You should only use it if 
mtoois gets the auto detected number of fat bits wrong or if you want to mformat a disk with 
a weird number of fatbits 

Only the file option is mandatory. The other parameters may be left out. In that case, a default value or an autodetected 
value isused. 

DRIVE GEOMETRY CON FIGURATION 

Geometry information describes the physical characteristics about the disk. Its has three purposes: 

mformat T he geometry information iswritten into the boot sector of the newly made disk. Howa/er, 

you may also describe the geometry information on the command line. Seemformat(l) for 
details. 

filtering On some Unices, da/ice nodes only support one physical geometry. The geometry is 

compared to the actual geometry stored on the boot sector to make sure that this device 
node is able to correctly read the disk. If the geometry doesn't match, this drive entry fails, 
and the next drive entry bearing the same drive letter is tried. See the next section "Supply¬ 
ing M ultipleD escriptions for a Drive" for more details on supplying several descri ptionsfor 
a drive letter. 

If no geometry information is supplied in the configuration file all disks are accepted. On 
Linux (and on Sparc), there exist device nodes with configurable geometry (/dev/fdo, /dew 
fdi etc), so filtering is not needed (and ignored) for disk drives, (mtoois still does do 
filtering on plain files (disk images) in Linux: This is mainly intended for test purposes 
because I don'thaveaccesstoaUNIX that would actually need filtering.) 
initial geometry T he geometry information (if available) is also used to set the initial geometry on 

configurable device nodes. This initial geometry isused to read the boot sector, which 
contains the real geometry. If no geometry information issupplied in theconfiguration file, 
no initial configuration is done. On Linux, this is not really needed either because the 
configurable devices are able to autodetect the disk type accurately enough (for most 
common formats) to read the boot sector. 

Wrong geometry information may lead to very bizarre errors. That's why I strongly recommend that you don't use geometry 
configuration unless you really need it. 

The following geometry related variables are available: 
cylinders T he number of cyli nders. 

heads T he number of heads(sides). 

T he number of sectors per track. 


use_xdf 

partition 

offset 

fat_bits 



sectors 
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For example, thefollowing drivesection describesa 1.44M drive: 
drive a: 

file="/dev/fd0H1440" 
fat_bits=12 

tracks=80 heads=2 sectors=18 

The following shorthand geometry descriptions are available 

1.44M H igh density, 3 1/2 disk. Equivalent to fat_bits=i 2 tracks =80 heads =2 sectors=i8. 

1.2M H igh density, 5 1/4 disk. Equivalent to fat_bits =12 tracks =80 heads =2 sectors=15. 

720K D ouble density, 3 1/2 disk. Equivalent to fat_bits =12 tracks =80 heads =2 sectors=9. 

360K D Ouble density, 5 1/4 disk. Equivalent to fat_bits =12 tracks=40 heads =2 sectors=9. 

The shorthand format descriptions may be amended. For example, 360K sectors=8 describes a 320K disk and is equivalent to 
fat_bits=12 tracks=40 heads=2 sectors=8. 

OPEN FLAGS 

M oreover, the following flags are available: 

sync All I/O operations are done synchronously. 

nodeiay T he device or file is opened with the o_ndelay flag. This is needed on some non-Linux 

architectures. 

exclusive T hedeviceor file is opened with the o_excl flag. On Linux, thisensuresexclusiveaccessto 

the floppy drive. 0 n most other architectures and for plain files, it has no effect at all. 

SUPPLYING MULTIPLE DESCRIPTIONSFOR A DRIVE 

It is possible to supply multiple descriptions for a drive. In that case, the descriptions are tried in order until one is found 
that fits. Descriptionsmay fail for several reasons: 

■ The geometry is not appropriate 

■ Thereisno disk in thedrive 

■ Other problems 

M ultiple definitions are useful when using physical devices that are only able to support one single disk geometry: 

drive a: file="/dev/fd0H1440" 1.44m 
drive a: file="/dev/fd0H720" 720k 

This instructs mtools to use /dev/tdOHmo for 1.44M (high density) disks and /dev/fd0H720 for 720K (double density) disks. 
On Linux, this feature is not really needed because the /dev/fdo device is able to handle any geometry. 

You can also use multi pie drive descriptions to access both of your physical drives through one drive letter: 

drive z: file="/dev/fd0" 
drive z: file="/dev/fd1" 

With this description, mdir z: accesses your first physical drive if it contains a disk. If the first drive doesn't contain a disk, 
mtools checks the second drive. 

When using multiple configuration files, drive descriptions in the files parsed last override descriptions for the same drive in 
earlier files. In order to avoid this, usethedrive+ or+drive keywords instead of drive. The first adds a description to the end 
of the list (will be tried last), and the second adds it to the start of the list. 

CHARACTER TRANSLATION TABLES 

If you live in theU SA, in W estern Europe or in Australia, you can skip this section. 
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INTRODUCTION 

DOS uses a different character code mapping from UNIX. Sa/en-bit characters still have the same meaning; only characters 
with the eight-bit set are affected. T o make matters worse, there are several translation tables available depending on the 
country where you are. The appearance of the characters is defined using codepages. These code pages aren't the same for all 
countries. For instance, some code pages don't contain upper-case accented characters. On the other hand, some code pages 
contain characters that don't exist in U NIX, such ascertain line-drawing characters or accented consonants used by some 
Eastern European countries. This affects two things relating to filenames: 

U ppercase characters In short names, only uppercase characters are allowed. This also holds for accented 

characters. For instance, in a code page that doesn't contain accented uppercase characters, 
the accented lowercase characters get transformed into their unaccented counterparts 
Long filenames M icrosoft has finally come to their senses and uses a more standard mapping for the long 

filenames. They use Unicode, which is basically a 32-bit version of ASCII. Its first 256 
characters are identical to U NIX ASCII. Thus, the code page also affects the correspondence 
between the codes used in long names and those used in short names. 

mtoois considers thefilenames entered on the command line as having the U NIX mapping and translates the characters to 
get short names. By default, code page 850 is used with the Swiss uppercas^lowercase mapping. I chose this code page 
because its set of existing characters most closely matches U NIX's. M oreover, this code page covers most characters i n use in 
theU SA, Australia, and Western Europe. FI owever, it isstill possible to chose a different mapping. There are two methods: 
the country variable and explicit tables. 

CONFIGURATION USING COUNTRY 

The country variable is recommended for people that also have access to M S-D OS system files and documentation. If you 
don't have access to these, I'd suggest you use explicit tables instead. 

Syntax: COUNTRY=" country [,[ codepage ], country.sys ]" 

This tells mtoois to use a U N IX-to-D OS translation table that matchescodepage and an lowercase-to-uppercase table for 
country andto usethecountry. sys fileto get the lowercase-to-uppercase table. T he country code is most often the telephone 
prefix of the country. Refer to the DOS help page on country for more details. The codepage and the country, sys parameters 
are optional. D on'ttypein the square brackets; they are only thereto indicate which parameters are optional. The 
country, sys fi le is supplied with M S-D OS. In most cases, you don't need it because the most common translation tables are 
compiled into mtoois. Don't worry if you run aUN IX-only box that lacks this file 

If codepage isnot given, a per-country default code page is used. If the country, sys parameter isn't given, compiled-in 
defaults are used for the lowercase-to-uppercase table. This is useful for other Unices than Linux, which may have no 
country, sys fi le available online. 

TheU N IX-to-D OS are not contained in the country, sys file and thus mtoois always uses compiled-in defaults for those. 
Thus, only a limited amount of codepages are supported. If your preferred code page is missing, or if you know the name of 
theW indows95 file that contains this mapping, drop me a lineatAiain.Knaff@inriaipes.fr. 

ThecouNTRY variablecan also beset using the environment. 

CONFIGURATION USING EXPLICIT TRANSLATION TABLES 

T ranslation tables may be described in lines in the configuration file. Two tables are needed: first the D OS-to-U NIX table 
and then the lowercase-to-uppercase table A D OS-to-U N IX table starts with thetounix keyword, followed by a colon and 
128 hexadecimal numbers. A lower-to-upper table starts with thefucase keyword, followed by a colon and 128 hexadecimal 
numbers. 

The tables only show the translations for characters whose codes is greater than 128 because translation for lower codes is 
trivial. Example: 
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tounix: 


0xc7 

0 xfc 

0xe9 

0 xe2 

0xe4 

0 xe0 

0xe5 

0xe7 

0 xea 

0 xeb 

0 xe8 

0 xef 

0 xee 

0 xec 

0xc4 

0xc5 

0xc9 

0 xe6 

0 xc6 

0xf4 

0 xf6 

0 xf2 

0 xfb 

0xf9 

0 xff 

0 xd6 

0 xdc 

0 xf8 

0xa3 

0 xd8 

0xd7 

0x5f 

0 xe1 

0 xed 

0xf 3 

0 xfa 

0 xf 1 

0 xd1 

0 xaa 

0 xba 

0 xbf 

0 xae 

0 xac 

0 xbd 

0 xbc 

0 xa1 

0 xab 

0 xbb 

0x5f 

0x5f 

0x5f 

0x5f 

0x5f 

0 xc1 

0 xc2 

0 xc0 

0xa9 

0x5f 

0x5f 

0x5f 

0x5f 

0 xa2 

0xa5 

0 xac 

0x5f 

0x5f 

0x5f 

0x5f 

0x5f 

0x5f 

0xe3 

0xc3 

0x5f 

0x5f 

0x5f 

0x5f 

0x5f 

0x5f 

0x5f 

0xa4 

0 xf0 

0 xd0 

0xc9 

0 xcb 

0 xc8 

0x69 

0 xcd 

0 xce 

0 xcf 

0x5f 

0x5f 

0x5f 

0x5f 

0x7c 

0x49 

0x5f 

0xd3 

0 xdf 

0xd4 

0 xd2 

0xf5 

0xd5 

0xb5 

0 xfe 

0 xde 

0 xda 

0xd9 

0 xfd 

0 xdd 

0 xde 

0 xaf 

0xb4 

0 xad 

0 xb1 

0x5f 

0 xbe 

0 xb6 

0xa7 

0xf 7 

0 xb8 

0 xb0 

0 xa8 

0xb7 

0xb9 

0xb3 

0 xb2 

0x5f 

0x5f 

fucase: 







0x80 

0x9a 

0x90 

0 xb6 

0 x8e 

0xb7 

0 x8f 

0x80 

0 xd2 

0xd3 

0xd4 

0 xd8 

0xd7 

0 xde 

0 x8e 

0 x8f 

0x90 

0x92 

0x92 

0 xe2 

0x99 

0xe3 

0 xea 

0 xeb 

0x59 

0x99 

0x9a 

0x9d 

0x9c 

0x9d 

0x9e 

0x9f 

0xb5 

0 xd6 

0 xe0 

0xe9 

0xa5 

0xa5 

0 xa6 

0xa7 

0 xa8 

0xa9 

0 xaa 

0 xab 

0 xac 

0 xad 

0 xae 

0 xaf 

0 xb0 

0 xb1 

0 xb2 

0xb3 

0xb4 

0xb5 

0 xb6 

0xb7 

0 xb8 

0xb9 

0 xba 

0 xbb 

0 xbc 

0 xbd 

0 xbe 

0 xbf 

0 xc0 

0 xc1 

0 xc2 

0xc3 

0xc4 

0xc5 

0xc7 

0xc7 

0 xc8 

0xc9 

0 xca 

0 xcb 

0XCC 

0 xcd 

0 xce 

0 xcf 

0 xd1 

0 xd1 

0 xd2 

0xd3 

0xd4 

0x49 

0 xd6 

0xd7 

0 xd8 

0xd9 

0 xda 

0 xdb 

0 xdc 

0 xdd 

0 xde 

0 xdf 

0 xe0 

0 xe1 

0 xe2 

0xe3 

0xe5 

0xe5 

0 xe6 

0 xe8 

0 xe8 

0xe9 

0 xea 

0 xeb 

0 xed 

0 xed 

0 xee 

0 xef 

0 xf0 

0 xf 1 

0 xf 2 

0xf3 

0xf4 

0xf5 

0 xf 6 

0xf 7 

0 xf8 

0xf9 

0 xf a 

0 xfb 

0 xfc 

0 xfd 

0 xfe 

0 xff 


The first table maps DOS character codes to UNIX character codes. For example the DOS character number 129 is a u with 
two dots on top of it. T o translate it into UN IX, we look at the character number 1 in the first table (1 =129 - 128). This is 
0 xt c. (Beware; numbering starts at 0.) T he second table maps lowercase DOS characters to uppercase DOS characters. T he 
same lowercase u with dots maps to character 0 x9a, which isan uppercaseU with dotsin DOS. 

UNICODE CHARACTERS G REATER THAN 256 

If an existing MS-DOS name contains Unicode character greater than 256, these are translated to underscores or to 
characters that are close in visual appearance. For example, accented consonants are translated into their unaccented 
counterparts. This translation is used formdir and for the U NIX filenames generated by mcopy. Linux does support Unicode 
too, but unfortunately, too few applications support it yet to bother with it in mtools. M ost importantly, xterm can't display 
Unicode yet. If there is sufficient demand, I might include support for Uni code in theU NIX filenames as well. 

Caution: W hen deleting files with mtools, the underscore matches all characters that can't be represented in U NIX. Be 
careful before mdei! 

LOCATION OF CON FIGURATION FILES AND PARSING ORDER 

The configuration files are parsed in the following order: 

Compiled-in defaults 
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/etc/mtools.conf 

/etc/mtoois. Thisisfor backwards compatibility only and isonly parsed if mtoois.conf doesn't exist. 

-/ .mtoolsrc 

Options described in the later files override those described in the earlier files. D rives defined in earlier files persist if they are 
not overridden in the later files. For instance, drives A and B may be defined in /etc/mtoois.conf and drives C and D may be 
defined in -/.mtoolsrc. H owever, if -/.mtoolsrc also defines drive A, thisnew description would override thedescription of 
drive A in /etc/mtoois.conf instead of adding to it. If you want to add a new description to a drive already described in an 
earlier file, you need to use either the +drive ordrive+ keywords. 

BACKWARDS COMPATIBILITY 

The syntax described herein is new for version mtoois 2.5.4. The old line-oriented syntax is still supported. Each line 
beginningwith a si ngle letter is considered to be a drive description using theold syntax. Old style and new style drive 
sections may be mixed within the same configuration file to makeupgrading easier. Support for theold syntax will be phased 
out eventually, and to discourage its use, I purposefully omit its description here. 

FILES 

/etc/mtools.conf 
'/ .mtoolsrc 


SEE ALSO 

mtools(l) 
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newsfeeds 

newsteeds— D etermine where U senet articles get sent. 

DESCRIPTION 

The file /news/iib/newsfeeds specifies how incoming articles should be distributed to other sites. It is parsed by the 
InterN etN ews server mnd(8) when it starts up or when directed to by ctiinnd(8). 

The file is interpreted as a set of lines according to the following rules. If a line ends with a backslash, then the backslash, the 
newline, and any whitespace at the start of the next line isdeleted. T his is repeated unti I the entire "logical" line is collected. 
If thelogical lineisblank or starts with a number sign (#), it isignored. 

All other lines are interpreted as feed entries. An entry should consist of four colon-separated fields; two of the fields may 
have optional subfields, marked off by a slash. Fields or subfields that take multiple parameters should be separated by a 
comma. Extra whitespace can cause problems. Except for the site names, case is significant. The format of an entry is 

si t e n a me [/exclude,e x c I ude,...]\ 

:pattern,pa11 er n...[/distrib,di st r i b... ]\ 

:flag,f I ag...\ 

:param 

Each field is described below. 

The si t e n a me is the name of the site to which a news article can be sent. It is used for writing log entries and for determining 
if an article should be forwarded to a site. If si tename already appears in the article's Path header, then the article will not be 
sent to the site. The name is usually whatever the remote site uses to identify itself in the Path line but can be almost any 
word that makes sense; special local entries (such as archivers or gateways) should probably end with an exclamation point to 
make sure that they do not have the same name as any real site. For example, gateway is an obvious name for the local entry 
that forwards articles out to a mailing list. If a site with the name gateway posts an article, when the local site receives the 
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article it will see the name in the Path and not send the article to its own gateway entry. If an entry has an exclusion subfield, 
then the article will not be sent to that site if any of the names specified as excludes appear in the Path header. T he same 
sitenamecan beused more than once; the appropriate action will betaken for each site that should receive the article, 
regardless of the name, although this is recommended only for program feedsto avoid confusion. Case is not significant in 
site names. 

The pat terns specify which groups to send to thesiteand are interpreted to build a "subscription list" for the site. The 
default subscription isto get all groups The patterns in thefield are wiidmat(3)-style patterns and are matched in order 
against the list of newsgroups that the local site receives. If the first character of a pattern is an exclamation mark, then any 
groups matching the pattern are removed from the subscription; otherwise, any matching groups are added. For example to 
receive all comp groups but only comp, sources, unix within the sources newsgroups, the following set of patterns can beused: 
comp.*,!comp.sources.*,comp.sources.unix 

There are three things to note about thisexample. Thefirst isthatthetrailing .* isrequired. Thesecond isthat, again, the 
result of the last match isthemost important. Thethird is that comp, sources.* could be written as comp.sources*, but this 
would not have the same effect if there were a comp, sources-only group. 

See innd(8) for details on the propagation of control messages. 

A subscription can be further modified by specifying "distributions" that the site should or should not receive. The default is 
to send all articles to all sites that subscribe to any of the groups where it has been posted, but if an article has a D istribution 
header and any distribs are specified, then they are checked according to the foil owing rules: 

1. If the D istribution header matches any of the values in the subfield, then the article is sent. 

2. If a distrib starts with an exclamation point and it matches the D istribution header, then the article is not sent. 

3. If D istribution header does not match any distrib in the site's entry and no negations were used, then the article is not 
sent. 

4. If D istribution header does not match any distrib in the site's entry and any distrib started with an exclamation point, 
then thearticleissent. 

If an article has more than one distribution specified, then each one is evaluated according to the preceding rules. If any of 
the specified distributions indicate that the article should be sent, it is. If none do, it is not sent: The rules are used as a 
"logical or.” It is almost definitely a mistake to have a single feed that specifies distributions that start with an exclamation 
point along with some that don't. 

D istributions are text words, not patterns; it is usually a mistake to have entries like* or ail there. 

T he f i ags parameter specifies miscellaneous parameters. They may be specified in any order; flags that take values should 
have the value immediately after the flag letter with no whitespace. The valid flags are 

< size An article will only be sent to the site if it is less than size bytes long. T he default is no 

limit. 

a checks An article will only be sent to the site if it meets the requirements specified i n thee hecks, 

which should be chosen from the following set: 
d D istribution header required 

p Do not check Path header before propagating. 

b hi gh/i ow If a site is being fed by a file, channel, or exploder, the server will usually start trying to write 

the information as soon as possible. Providing a buffer may give better system performance 
and help smooth out overall load if a large batch of news comes in. The value of the this flag 
should be two numbers separated by a slash. Thefirst specifies the point at which the server 
can start draining the feed's I/O buffer, and thesecond specifies when to stop writing and 
begin buffering again; the units are bytes. The default isto do no buffering, sending output 
as soon as it is possi ble to do so. 

f name This flag specifies the name of the file that should beused if it is necessary to begin spooling 

for the site. If name is not an absolute pathname, it is taken to be relative to /news/spool/ 
out. going. Then, if the desti nation is a directory, the file to go in that directory will beused 
as filename. 
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H count 


I 


size 


N mo d i f i e r s 


S 


size 


T 


type 


W i t e ms 


If this flag is specified, an article will only be sent to the site if it is posted to no more than 
count newsgroups. 

If thisflag is specified, an article will only be sent to the site if it has c ou nt or fewer sites in 
its Path line. Thisflag should only be used as a rough guide because of the loose interpreta¬ 
tion ofthePath header; some sites put the poster's name in the header, and some sites that 
might logically be considered to beonehop becometwo because they put the posting 
workstation's name in the header. The default value for count is one. 

T he flag spedfi es the size of the internal buffer for a fi le feed. I f there are more fi le feeds 
than allowed by the system, they will be buffered internally in least recently used order. If 
the internal buffer grows bigger than size bytes, however, the data will be written out to the 
appropriate file 

The newsgroups that a site receives are modified according to the modifiers, which should 
be chosen from the following set: 
m 0 nly moderated groups 

u 0 nly unmoderated groups 

If the amount of data queued for the site gets to be larger than si ze bytes, then the server 
will switch to spooling, appending to a file specified by the f flag or /news/spooi/out.going/ 
si t e n a me if the f flag is not specified. Spooling usually happens only for channel or exploder 
feeds. 

This flag specifies the type of feed for the site type should be a letter chosen from the 
following set: 
c Channel 

t File 

1 Log entry only 

m Funnel (multiple entries feed into one) 

p Program 

x Exploder. Each feed is described in the section on feed types. 

The default isTf. 

If a site is fed by file channel, or exploder, thisflag controls what information is written. If 
a si te i s fed by aprogram, only the asterisk (*) has any effect. The itemsshould be chosen 
from the following set: 
b Size of the article in bytes, 

f Article'sfull pathname. 

g The newsgroup the article is in; if cross-posted, then the first of the groups 

this site gets. 

m Article's Message-1 D. 

n Article's pathname relative to the spool directory, 

p The site that fed the article to the server; from the Path header, 

s ThelP address of thesitethat sent thearticle 

t Time article was received assecondssinceepoch. 

* Names of theappropriatefunnel entries; or all sites that get thearticle. 

d Value of the D istribution header; ? if none present. 

h All headers. 

n Value of the Newsgroups header. 

o Overviewdata. 

r Information needed for replication. M ore than one letter can be used; the 

entries will be separated by a space and written in the order in which they are 
specified. The default iswn. 



nan steeds 



T he h and o items are intended for use by programs that create news overview databases. If h 
is present, then the all the article's headers are written followed by a blank line. An Xref 
header (even if one does not appear in the filed article) and a Bytes header, specifying the 
article's size, will also be part of the headers. If used, this should be the only item in the list; 
if preceded by other items, however, a newline will be written before the headers. Theo 
generates input to theoverchan(8) program. It, too, should be the only item in the list. 

The asterisk has special meaning. It expands to a space-separated list of all sites that received 
the current article. If the site is the target of a funnel, however (that is, it is named by other 
sites that have aim flag), then the asterisk expands to the names of the funnel feeds that 
received the article. If thesiteisfed by a program, then an asterisk in theparam field will be 
expanded into the list of funnel feeds that received the article. A site fed by a program 
cannot get thesite list unless it isthe target of other Tm feeds. 

The interpretation of theparam field depends on the type of feed, and is explained in more detail in the section on feed types. 
It can be omitted. 

The site named me is special. There should only be one such entry, and it should be thefirst entry in the file. If the me entry 
has a subscription list, then that list is automatically prepended to the subscription list of all other entries. For example, 

*, i control, i junk, ifoo.* can be used to set up the initial subscription list for all feeds so that local postings are not propa¬ 
gated unlessfoo.* explicitly appears i n the site's subscription list. Note that most subscriptions should have; junk,icontroi 
in their pattern list; see the discussion of control messages in innd(8). (U nlike other news software, it does not affect what 
groups are received; that is done by the active(5) file.) 

If the me entry has a distribution subfield, then only articles that match the distribution list are accepted; all other articles are 
rejected. A commercial news server, for example, might have /1 local to rqect local postings from other, misconfigured, sites. 

FEED TYPES 

innd provides four basic types of feeds: log, file, program, and channel. An exploder is a special type of channel. In addition, 
several entries can feed into the same feed; these are funnel feeds, which refer to an entry that is one of the other types. N ote 
that the term "feed" is technically a misnomer because the server does not transfer articles but reports that an article should 
be sent to thesite. 

The simplest feed is one that is fed by a log entry. Other than a mention in the news logfile, no data is ever written out. This 
is equivalent to ait entry writing to /dev/nuii except that no file is opened. 

A site fed by a file is simplest type of feed. When the site should receive an article, one line is written to the file named by the 
par am field. If par am isnotan absolute pathname, itistaken to be relative to /news/spooi/out. going. If empty, thefilename 
defaults to /news/spaoi/out. going/si t ename . T hisnameshould beunique. 

When a site fed by a file is flushed (seectiinnd), the following steps are performed. The script doing the flush should have 
first renamed the file. The server tries to write out any buffered data and then closes the file. The renamed file is now 
available for use. The server will then reopen the original file, which will now get created. 

A site fed by a program has a process spawned for every article that the site receives. Theparam field must be a sprintf(3) 
format string that may haveasingle%s parameter, which will be given a path name for the article, relative to the news spool 
directory. The full pathname may be obtained by prefixing the%s in theparam field by the news spool directory prefix. 
Standard input will beset to the article or /dev/nuii if the article cannot be opened for some reason. Standard output and 
error will beset to the error log. The process will run with the user and group ID of the/news/iib/innd directory, innd will 
try to avoid spawning a shell if the command hasno shell meta-characters; this feature can bedefeated by appendinga 
semicolon to the end of the command. The full pathname of the program to be run must be specified; for security, path is 
not searched. 

If the entry is the target of a funnel, and if the w* flag is used, then a single asterisk may be used in theparam field where it 
will be replaced by the names of the sites that fed into the funnel. If the entry is not a funnel, orifthew* flag is not used, 
then the asterisk hasno special meaning. 
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Flushing a site fed by a program does no action. 

When a site is fed by a channel or exploder, the pa ram field names the process to start. Again, the full pathname of the process 
must be given. When the site is to receive an article, the process receives a line on its standard input telling it about the 
article. Standard output and error and the user and group ID of the all subprocess are set as for a program feed. If the process 
exits, it will be restarted. If the process cannot be started, the server will spool input to a file named /news/spooi/out.going/ 
s i t e n a me . It will then try to start the process sometime later. 

When a site fed by a channel or exploder is flushed, the server closes down its end of the pipe. Any pending data that has not 
been written will be spooled; see the description of the s flag. N o signal is sent; it is up to the program to notice EOF on its 
standard input and exit. T he server then starts a new process. 

Exploders are a superset of channel feeds. In addition to channel behavior, exploders can be sent command lines. These lines 
start with an exclamation point, and their interpretation is up to the exploder. The following messages are generated 
automatically by the server: 

newgroup group 
rmgroup group 
flush 
flush site 

These messages are sent when thectiinnd command of the same name is received by the server. In addition, the send 
command can be used to send an arbitrary command line to the exploder child-process. The primary exploder is buff chan(8). 

Funnel feeds provide a way of merging several site entries into a single output stream. For a site feeding into a funnel, the 
pa r a m field names the actual entry that does the feeding. 

For more details on setting up different types of news feeds, seetheINN installation manual. 

EXAMPLES 

## Initial subscription list and our distributions. 

ME:*,!junk,!foo.*/world,usa,na,ne,foo,ddn,gnu, inet\ 

## Feed all moderated source postings to an archiver 
source-archive!:!*,comp.sources.*\ 

:Tp,Nm:/usr/local/bin/archive %s 
## Watch for big postings 
watcher!:*\ 

:Tc,Wbnm\ 

:exec awk '$1 > 1000000 { print "BIG", $2, $3 }' >/dev/console 

## A UUCP feed, where we try to keep the "batching" between 4 and IK. 

ihnp4:/world,usa,na,ddn,gnu\ 

:Tf,Wfb,B4096/1024: 

## Usenet as mail; note ! in funnel name to avoid Path conflicts. 

## Can't use ! in "fred" since it would like look a UUCP address, 
fred:!*,comp.sources.unix,comp.sources.bugs\ 

:Tm:mailer! 

barney@bar.com:!*,news.software.nntp,comp.sources.bugs\ 

:Tm:mailer! 
mailer!:!*\ 

:W*,Tp:/usr/ucb/Mail -s "News article" * 

## NNTP feeds fed off-line via nntpsend or equivalent. 

feedl::Tf,Wnm:feed1.domain.name 

peer.foo.com:foo.*:Tf,Wnm:peer.foo.com 

## Real-time transmission. 

mit.edu:/world,usa,na,ne,ddn,gnu,inet\ 

:Tc,Wnm:/nntplink -i stdin mit.edu 

## Two sites feeding into a hypothetical NNTP fan-out program: 
nic.near.net:\ 

:Tm:nntpfunnel1 
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uunet.uu.net/uunet:!ne.*/world,usa,na,foo,ddn,gnu,inet\ 

:Tm:nntpfunnel1 
nntpfunnell:!*\ 

:Tc,Wmn*:/nntpfanout 

## A UUCP site that wants comp.* and moderated soc groups 
uucpsite!comp:!*,comp.*/world,usa,na,gnu\ 

:Tm:uucpsite 

uucpsite!soc:!*,soc.*/world,usa,na,gnu\ 

:Tm,Nm:uucpsite 
uucpsite:!*\ 

:Tf,Wfb:/usr/spool/batch/uucpsite 

The last two sets of entries show how funnel feeds can be used. For example the nntpfanout program would receive lines like 
the following on its standard input: 

<123@litchi.foo.com> comp/sources/unix/888 nic.near.net uunet.uu.net 
<124@litchi.foo.com> ne/general/1003 nic.near.net 

BecausetheUUCP funnel is only destined for one site the asterisk is not needed and entries like the following will be 
written into thefile: 

<qwe#37x@snark.uu.net>comp/society/folklore/3 
<123@litchi.foo.com> comp/sources/unix/888 

HISTORY 

W ritten by Rich $alz (nsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

active(5), buff chan (8), ctlinnd (8), innd(8), wildmat(3) 

newslog 

newsiog— Description of Usenet log files. 

DESCRIPTION 

M ost log files created by Usenet programs reside in the/var/iog/news directory and have a .log extension. Several versions 
are usually kept with an additional extension such as . 1 , . 2 , and so on; the higher the number, the older the log. The older 
versionsarecomp ressed. 

T he scaniogs script and related utilities (see newsiog(8)) are responsiblefor rotating and compressing these files. 

Some log files always have data, others only have data if there is a problem, and others are only created if a particular 
program is used or configuration parameter is set. Theinnstat script (see newsiog(8)) monitors the size of all log files. 

Thefollowing files will only accumulate data under the direction of control. cti(5): 

control.log, miscctl.log, newgroup.log, rmgroup.log, unwanted.log 

In order to create these files, the message and action fields of control, cti should be chosen from the following table: 


M esage 

Action 

M eaning 

all 

log=miscctl 

Log all messages by default 

default 

log=miscctl 

Log unknown messages 

newgroup 

doit=newgroup 

C reate group and log message 

newgroup 

log=newgroup 

Log message 


continues 
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M esage 

Action 

M eaning 

rmgroup 

doit=rmgroup 

Remove group and log message 

rmgroup 

log=rmgroup 

Log message 

“other" 

doit=miscctl 

Log and process the message 

“other" 

log=miscctl 

Log message 


H ere, "other" refersto any other control message such as: 
checkgroups ihave sendme sendsys senduuname version 


The following is a list of log files. 


control.log 


errlog 

expire.log 

miscctl.log 

newgroup.log 

news 

news.crit 

news.err 

news.notice 

nntpsend.log 

rmgroup.log 

unwanted.log 


T his file maintains a count of the number of newgroup and rmgroup control messages seen for 
each newsgroup. The count is of the number of control messages with identical arguments, 
regardless of whether they were actually processed. All control arguments, including invalid 
ones, are counted. Thisfileisupdated by tally.control, which isinvoked byscaniogs if 
either the newgroup or rmgroup logs exist. This file is not rotated. 

Thisfilecontains the standard output and standard error of any program spawned by 
innd(8). The most common programsarethecontrol-message handlers found in /news/bin/ 
control. T his file should be empty. Scanlogs will print the entire contents of this log file if it 
is non-empty. 

By default, when news.daily isgoingto expireold news articles, it writesthedateto this 
file, followed by any output from expire(8) and the ending date. All lines but the first are 
indented four spaces. 

When control, cti isconfigured as described above all control messages except newgroup 
and rmgroup are appended to thisfile by writeiog. There will be a summary line describing 
themessageand theaction taken, followed by the article indented by four spaces and a 
blank line. 

When control.cti isconfigured as described above all newgroup messages are appended to 
thisfileusingthesameforrnatasformisccti.log. 

Thisfile logs articles received by innd. scanlogs summarizes the rqected articles reported in 
thisfile. 

All critical error messages issued by innd are appended to this file via sysiog(3). This log file 
should be empty, scanlogs will print theentire contents of this log file if it is non-empty. 
You should havethefollowing line in yoursysiog.conf(5) file: 
news.crit /var/log/news/news.crit 

All major error messages issued by innd are appended to thisfile via sysiog. This log file 
should be empty, scanlogs will print theenti re contents of this log fi le if it is non-empty. 
You should have thefollowing linein your sysiog.conf file 
news.err /var/log/news/news.err 

All standard error messages and status messages issued by innd are appended to thisfile via 
sysiog. scanlogs uses the awk(l) script inniog.awk to summarize thisfile You should have 
thefollowing line in your sysiog.conf file: 
news.notice /var/log/news/news.notice 
T he nntpsend(8) programs appends all status messages to thisfile. 

When control, cti isconfigured as described previously, all rmgroup messages are appended 
to thisfile usi ng the same format as for misccti. log. 

This log maintains a count of the number of articles that were rejected because they were 
posted to newsgroups that do not exist at the local site. Thisfileisupdated by 
tally.unwanted and maintained in reverse numeric order (the most popular rejected group 
first). Thisfile is not rotated. 



HISTORY 

Written by Landon Curt N oil (chongo@toad.com) and Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews 

SEE ALSO 

control.ctl(5j, ctlinnd(8j, expire(8j, innd(8j, news.daily(8j, nntpsend(8j, newslog(8j 


nfs 

nfs— NFS tstab format and options. 

SYNOPSIS 

/etc/fstab 


DESCRIPTION 

T he tstab file contains information about which filesystems to mount where and with what options. For N FS mounts, it 
contains the server name and exported server directory to mount from, the local directory that is the mount point, and the 
N FS-specific options that control the way the filesystem is mounted. FI ere is an example from an /etc/fstab file from an 
N FS mount. 

server:/usr/local/pub /pub nfs rsize=8192,wsize=8192,timeo=14,intr 


OPTIONS 

rsize=n 


wsize=n 


timeo=n 


retrans=n 

acregmin=n 

acregmax=n 

acdirmin=n 

acdirmax=n 

actimeo=n 


The number of bytes N FS uses when reading files from an N FS server. The default value is 
dependent on the kernel, currently 1024 bytes. (FI owever, throughput is improved greatly by 
asking for rsize=8192.) 

The number of bytes N FS uses when writing files to an N FS server. The default value is 
dependent on the kernel, currently 1024 bytes. (FI owever, throughput is improved greatly by 
asking for wsize=8i92.) 

The value in tenths of a second before sending the first retransmission after an RPC time¬ 
out. The default value is 7 tenths of a second. After the first time-out, the time-out is 
doubled after each successive time-out until a maximum time-out of 60 seconds is reached 
or the enough retransmissions have occurred to cause a major time-out. T hen, if the 
filesystem ishard mounted, each new time-out cascade restarts at twice the initial value of 
the previous cascade, again doubling at each retransmission. The maximum time-out is 
always 60 seconds. Better overall performance may be achieved by increasingthetime-out 
when mounti ng on a busy network, to a slow server, or through several routers or gateways. 
T he number of minor time-outs and retransmissions that must occur before a major time¬ 
out occurs. The default is 3 time-outs. W hen a major time-out occurs, thefile operation is 
either aborted or a "server not responding” message is printed on the console. 

The minimum time in seconds that attributes of a regular file should be cached before 
requesting fresh information from a server. T he default is 3 seconds. 

The maximum time in seconds that attributes of a regular file can be cached before 

requesting fresh information from a server. T he default is 60 seconds 

The minimum time in seconds that attributes of a directory should be cached before 

requesting fresh information from a server. T he default is 30 seconds 

The maximum time in seconds that attributes of a directory can be cached before requesting 

fresh information from a server. T hedefault is 60 seconds. 

U Sing actimeo sets all Of acregmin, acregmax, acdirmin, and acdirmax to the Same value. T here 
is no default value. 
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retry=n 

namlen=n 

port=n 

mountport=n 

mounthost=name 

mountprog=n 

mountvers=n 

nfsprog=n 

nfsvers=n 

bg 

fg 

soft 

hard 

intr 

posix 

nocto 

noac 

top 

udp 


FILES 


The number of times to retry a backgrounded N FS mount operation before giving up. The 
default value is 10000 times. 

When an N FS server does not support version 2 of the RPC mount protocol, this option 
can be used to specify the maxi mum length of a filename that is supported on the remote 
filesystem. This is used to support the POSIX pathconf functions. The default is255 
characters. 

The numeric value of the port to connect to theN FS server on. If the port number ise (the 
default) then query the remote host's port mapper for the port number to use. If the remote 
host's NFS daemon is not registered with its port mapper, the standard N FS port number 
2049 is used instead. 

T he numeric value of the mountd port. 

T he name of the host running mountd. 

Use an alternate RPC program number to contact the mount daemon on the remote host. 
This option is useful for hosts that can run multiple N FS servers. The default value is 
100005 , which isthestandard RPC mount daemon program number. 

U se an alternate RPC version number to contact the mount daemon on the remote host. 
This option is useful for hosts that can run multiple N FS servers. The default value is 
version 1 . 

Use an alternate RPC program number to contact the N FS daemon on the remote host. 
This option is useful for hosts that can run multiple N FS servers. The default value is 
100003 , which isthe standard RPC N FS daemon program number. 

Use an alternate RPC version number to contact theN FS daemon on the remote host. This 
option is useful for hosts that can run multiple N FS servers. The default value is version 2 . 

If the first N FS mount attempt times out, continue trying the mount in the background. 
The default is to not to background the mount on time-out but to fail. 

If the first N FS mount attempt times out, fail immediately. This isthe default. 

If an N FS file operation has a major time-out, then report an I/O error to the calling 
program. The default is to continue retrying N FS file operations indefinitely. 

If an N FS file operation has a major time-out, then report "server not responding" on the 
consoleand continue retrying indefinitely. This is the default. 

If an N FS file operation has a major time-out and it is hard mounted, then allow signals to 
interrupt the file operation and cause it to return eintr to the calling program. The default 
isto not allow file operations to be interrupted. 

M ounttheN FSfilesystem using POSIX semantics. This allows an N FSfilesystem to 
properly support the POSIX pathconf command by querying the mount server for the 
maximum length of a filename. To do this, the remote host must support version 2 of the 
RPC mount protocol. M any N FS servers support only version 1. 

Suppress the retrieval of new attributes when creating a file. 

D isableall forms of attribute caching entirely. This extracts a server performance penalty, 
but it allows two different N FS clients to get reasonably good results when both clients are 
actively writing to a common filesystem on the server. 

M ounttheN FSfilesystem using theT CP protocol instead of the default UDP protocol. 

M any N FS severs only support UDP. 

M ounttheN FSfilesystem using the U D P protocol. This isthe default. All the non-value 
options have corresponding nooption forms. For example, nointr meansdon't allow file 
operations to be interrupted. 


/etc/fstab 
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SEE ALSO 

fstab(5), mount(8), umount(8), exports(5) 

AUTHOR 

Rick Sladkey (jns@wonld.stcl.com) 

BUGS 

Thebg, tg, netny, posix, and nocto options are parsed by mount but currently are silently ignored. The tcp and namien 
options are implemented but are not currently supported bytheLinux kernel. The mount command should notify the server 
when an N FSfilesystem isunmounted. 

Linux0.99, 20 November 1993 


nnrp.access 

nnnp. access— Access file for on-campus N NTP sites. 

DESCRIPTION 

Thefile /news/iib/nnnp. access specifies the access control forthoseN NTP sites that are not handled bythemain 
InterN etN ewsdaemon innd(8). Thennnpd(8) server reads it when first spawned by innd. 

Comments begin with a number sign (#) and continue through the end of the line. Blank lines and comments are ignored. 

All other lines should consist of five fields separated by colons 

hosts : p e r ms : u s e r n a me: p a s s wo r d : p a 11 e r n s 

The first field is a wiidmat(3)-style pattern specifying the names or Internet address of a set of hosts. Before a match is 
checked, theclient'shostname(or its Internet address if gethostbyaddr(3) fails) isconverted to lowercase. Each lineis 
matched in turn, and the last successful match istaken as the correct one 

Thesecond field is a set of letters specifying the permissions granted to theclient. Theperms should be chosen from the 
following set: 

r The client can retrieve articles 

p Theclientcan postarticles 

The third and fourth fields specify the user name and pass nurd that the client must use to authenticate them selves before the 
server will accept any articles. N otethat no authentication (other than a matching entry in thisfile) is required for 
newsreading. If they are empty, then no password is required. Whitespace in these fields will result in theclient being unable 
to properly authenticate themselves and may be used to disable access. 

The fifth field is a set of patterns identifying the newsgroups that the client is allowed to access. Thepat ter ns are interpreted 
in the same manner as the newsfeeds(5) file. The default, however, denies access to all groups 

The access file is normally used to provide host-level access control for reading and posting articles. There are times, however, 
when this is not sufficient and user-level access control is needed. Whenever an N NTP authinto command is used, thennrpd 
server rereads this file and looks for a matching username and password. If the local newsreaders are modified to send the 
authinto command, then all host entries can have no access and specific users can be granted the appropriate read and post 
access. For example: 

## host:perm:user:pass:groups 
## Default is no access. 

:: -no- : -no- :!* 

## FOO hosts have no password, can read anything. 

.foo.com:Read Post:::* 

## A related workstation can't access FOO newsgroups, 
lenox.foo.net:RP:martha:hiatt:*,!too.* 
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If the filecontains passwords, it should not be world-readable. 

HISTORY 

W ritten by Rich $alz (nsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

lnnd(8), newsfeeds(5), nnrpd(8), wildmat(3) 

nntpsend.ctl 

nntpsend.ctl — List of sites to feed via nntpsend. 

DESCRIPTION 

The file /news/lib/nntpsend.ctl specifies the default list Of sites to be fed by nntpsend(8). 

Comments begin with a number sign (#) and continue through the end of the line. Blank lines and comments are ignored. 
All other lines should consist of four fields separated by a colon. 

Thefirst field isthenameof the site as specified in the newsfeeds(5) file. 

The second field should be the hostname or IP address of the remote site. 

The third field, if non-empty, specifies the default tail truncation size of site's batchfile This is passed to shrinkfiie as the -s 
flag. If thisfield isempty, no truncation is performed. 

Thefourth field specifies some default flags passed to innxmit(8). T heflag -a isalways given to innxmit and need not appear 
here. I f no -t timeout flag isgiven in thisfield and on the nntpsend command line, -t iso will be given to innxmit. 

HISTORY 

W ritten by Landon Curt N oil (chongo@toad.com) for InterN etN ews. 

SEE ALSO 

innxmit(8), newsfeeds(5), nntpsend(8), trunc(l) 


nologin 

noiogm— Prevent usual users from logging into thesystem. 

DESCRIPTION 

If thefile /etc/noiogin exists, iogin(l) will allow access only to root. Other users will be shown the contents of thisfile and 
their logins refused. 

FILES 


/etc/nologin 


SEE ALSO 

login(l), shutdown(8) 


Linux, 29 December 1992 


overview.fmt 


overview.fmt— Format of news overview database. 



paswcf 



DESCRIPTION 

The file /news/iib/overview.fmt specifies the organization of the news overview database. Blank lines and lines beginning 
with a number sign (#) are ignored. The order of lines in this file is important; it determines the order in which the fields will 
appear in the database. 

M ost lines will consist of an article header name, optionally followed by a colon. A trailing set of lines can have the word tun 
appear after the colon; this indicates that the header should appear as well as its value. 

If this file is changed, it is usually necessary to rebuild the existing overview database using expireover(8) after removing all 
existing overview files. 

The default file, show here, iscompatiblewith Geoff Col Iyer's nov package: 

Subject: 

From: 

Date: 

Message-ID: 

References: 

Bytes: 

Lines: 

## Some newsreaders get better performance if Xref is present 
#Xref:full 

HISTORY 

W ritten by Rich $alz (rsaiz@uunet.uu.net) for I nterN etN ews. Intended to be compatible with the nov package written by 
Geoff Col Iyer (geoff@world.std.com). 

passwd 

passwd— Password file. 

DESCRIPTION 

passwd is an ASCII file that contains a list of the system's users and the passwords they must use for access. The password file 
should have general read permission (many utilities, such asis(l), use it to map user IDs to usernames) but write access only 
for the superuser. 

In the good old days, there was no great problem with this general read permission. Everybody could read the encrypted 
passwords, but the hardware was too slow to crack a well-chosen password, and moreover, the basic assumption used to be 
that of a friendly user community. These days, many people run some version of the shadow password suite, where /etc/ 
passwd has *s instead of passwords, and the encrypted passwords are in /etc/shadow, which is readable by root only. 

When you create a new login, leave the password field empty and usepasswd(l) to fill it. A star (*) in the password field 
means that this user cannot log in via iogm(l). 

There is one entry per line, and each line has the format: 

I ogi n_name : p ass wd:UI D:GI D:user_name:di rectory: s h e I I 


Thefield descriptionsare 


1 ogi n _ n a me 

The name of the user on the system. 

password 

The encrypted optional user password. 

Ul D 

The numerical user ID. 

Gl D 

The numerical group ID for this user. 

username 

The(optional) comment field (often afull username) 

di rectory 

The user's $home directory. 

shell 

Theprogram to run at login (if empty, use /bin/sh). 
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NOTE 

If your root fi le system ison /dev/ram, you must saveachanged password fileto your root filesystem floppy before you shut 
down the system and check the access rights. If you want to create user groups, their GID s must be equal and there must be 
an entry in /etc/group, or no group will exist. 

FILES 

/etc/passwd 


SEE ALSO 

passwd(l), login(l), group(5), shadow(5) 
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passwd.nntp 

passwd.nntp— Passwords for connecting to remote N NTP servers. 

DESCRIPTION 

The file /news/iib/passwd.nntp contains host-name- password triplets for use when authenticating client programs to N NTP 
servers. T hisfile is normally interpreted by the NNTPsend-password routinein iibinn(3). Blank lines and lines beginning with 
a number sign (#) are ignored. All other lines should consist of three or fields separated by colons: 

host : n a me : p a s sword 
host : n a me : p a s sword: s t y I e 

The first field is the name of a host and is matched in a case-insensitive manner. The second field is a username, and the 
third isa password. The optional fourth field specifies the type of authentication to use. The default isauthinfo, which 
means that N NTP authinto commands are used to authenticate to the remote host. If either the username or password are 
empty, then the related command will not be sent. (Theauthinto command isacommon extension to RFC 977.) For 
example: 

## UUNET needs a password, MIT doesn't. 

mit.edu:bbn::authinfo 

uunet.uu.net:bbn:yoyona:authinto 

T hisfile should not be world-readable. 

HISTORY 

W ritten by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

innd(8), libinn(3) 

pbm 

pbm— Portable bitmap fileformat. 

DESCRIPTION 

The portable bitmap format isa lowest common denominator monochrome file format. It was originally designed to make it 
reasonableto mail bitmaps between different types of machines using thetypical stupid network mailers we have today. Now 
it serves as the common language of a large family of bitmap conversion filters. The definition is as follows: 

A "magic number” for identifying thefile type. A pbm file's magic number is the two characters pi. 



pgm 



Whitespace (blanks, Tabs, CRs, LFs). 

A width, formatted asASCII characters in decimal. 

Whitespace. 

A height, again in ASCII decimal. 

Whitespace. 

Width * height bits, each either i ora, starting at the top-left corner of the bitmap, proceeding in normal English reading 
order. 

The character i means black; 0 means white 
Whitespace in the bits section isignored. 

Characters from a# to the next end-of-line are ignored (comments). 

No line should be longer than 70 characters. 

H ere is an example of a small bitmap in this format: 
pi 

# feep.pbm 
24 7 

000000000000000000000000 
011110011110011110011110 
010000010000010000010010 
011100011100011100011110 
01 000001 000001 000001 0000 
010000011110011110010000 
000000000000000000000000 

Programs that read thisformat should be as lenient as possible, accepting anything that looks remotely likea bitmap. 

There is also a variant on the format, available by setting the rawbits option at compile time. This variant is different in the 
following ways: 

The"magic number” isP4 instead of pi. 

The bits are stored eight per byte, high bit first and low bit last. 

N 0 whitespace is all owed in the bits section, and only a single character of whitespace (typically a newline) is allowed after 
the height. 

Thefiles areeighttimes smaller and many timesfasterto read and write. 

SEE ALSO 

atktopbm(l), brushtopbm(l), cmuwmtopbm(l), g3topbm(l), gemtopbm(l), icontopbm(l), macptopbm(l), mgrtopbm(l), pi3topbm(l), 
xbmtopbm(l), ybmtopbm(l), pbmto10x(l), pnmtoascii(l), pbmtoatk(l), pbmtobbnbg(l), pbmtocmuwm(l), pbmtoepson(l), pbmtog3(l), 
pbmtogem(l), pbmtogo(l), pbmtoicon(l), pbmtolj(l), pbmtomacp(l), pbmtomgr(l), pbmtopi3(l), pbmtoplot(l), pbmtoptx(l), 
pbmtox10bm(l), pbmtoxbm(l), pbmtoybm(l), pbmtozinc(l), pbmlife(l), pbmmake(l), pbmmask(l), pbmreduce(l), pbmtext(l), 
pbmupc(l), pnm(5), pgm(5), ppm(5) 

AUTHOR 

Copyright 1989,1991 byjef Poskanzer. 

27 September 1991 


pgm 

pgm — Portable graymap file format. 
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DESCRIPTION 

The portable graymap format is a lowest common denominator grayscale file format. The definition is as follows: 

A "magic number” for identifying thefile type. A pgm file's magic number is the two characters P 2 . 

Whitespace (blanks, Tabs, CRs, LFs). 

A width, formatted asASCII characters in decimal. 

Whitespace. 

A height, again in ASCII decimal. 

Whitespace. 

Themaximum gray value, again in ASCII decimal. 

Whitespace. 

Width * height gray values, each in ASCII decimal, between 0 and the specified maximum value, separated by whitespace, 
starting at the top-left corner of the graymap, proceeding in normal English reading order. A value of 0 means black, and the 
maximum value means white. 

C haracters from a # to the next end-of-line are ignored (comments). 

No line should be longer than 70 characters. 

H ere is an example of a small graymap in this format: 

P2 

# feep.pgm 
24 7 
15 

000000000000000000000000 
033330077770011 11 1111 0 0 15 1515 15 0 
030000070000011 00000 15 00 150 
033300077700011 11 110 0 0 15 15 15 150 
030000070000011 00000 15 0000 
030000077770011 11 1111 0 0 15 0 0 0 0 
000000000000000000000000 

Programs that read this format should be as lenient as possible, accepting anything that looks remotely I ike a graymap. 

There is also a variant on the format, available by setting the rawbits option at compile time. This variant is different in the 
following ways: 

The"magic number" is ps instead of P 2 . 

The gray values are stored as plain bytes, instead of ASCII decimal. 

N o whitespace is allowed in the grays section, and only a single character of whitespace (typically a newline) is allowed after 
themaxval. 

Thefiles are smaller and many times faster to read and write 

N otethat this raw format can only be used for maxvals less than or equal to 255 . If you use the pgm library and try to write a 
file with a larger maxval, it will automatically fall back on the slower but more general plain format. 

SEE ALSO 

fitstopgm(l), fstopgm(l), hipstopgm(l), lispmtopgm(l), psidtopgm(l), nawtopgm(l), pgmbentley(l), pgmcrater(l), pgmedge(l), 
pgmenhance(l), pgmhist(l), pgmnorm(l), pgmoil(l), pgmramp(l), pgmtexture(l), pgmtofits(l), pgmtofs(l), pgmtolispm(l), 
pgmtopbm(l), pnm(5), pbm(5), ppm(5) 

AUTHOR 

Copyright 1989,1991 byjef Poskanzer. 


12 N ovember 1991 
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pnm 

pnm — Portable anymap fi le format. 

DESCRIPTION 

The pnm programsoperateon portable bitmaps, graymaps, and pixmaps produced bythepbm, pgm, and ppm segments. There is 
no file format associated with pnm itself. 

SEE ALSO 

anytopnm(l), rasttopnm(l), tifftopnm(l), xwdtopnm(l), pnmtops(l), pnmtorast(l), pnmtotiff(1), pnmtoxwd(l), pnmarith(l), 
pnmcat(l), pnmconvol(l), pnmcrop(l), pnmcut(l), pnmdepth(l), pnmenlarge(l), pnmfile(l), pnmflip(l), pnmgamma(l), pnmindex(l), 
pnminvert(l), pnmmargin(l), pnmnoraw(l), pnmpaste(l), pnmrotate(l), pnmscale(l), pnmshear(l), pnmsmooth(l), pnmtile(l), 
ppm(5), pgm(5), pbm(5) 

AUTHOR 

Copyright 1989,1991 byjef Poskanzer. 

27 September 1991 


ppm 

ppm— Portable pixmap fi le format. 

DESCRIPTION 

The portable pixmap format is a lowest common denominator color image file format. The definition is as follows: 

A "magic number” for identifying thefile type. A ppm file's magic number is the two characters P3. 

W hitespace (blanks, Tabs, C Rs, LFs). 

A width, formatted asASCII charactersin decimal. 

Whitespace. 

A height, again in ASCII decimal. 

Whitespace. 

The maximum color-component value, again in ASCII decimal. 

Whitespace. 

Width * height pixels, each three ASC11 decimal values between 0 and the specified maximum value, starting at the top-left 
corner of the pixmap, proceeding in normal English reading order. The three values for each pixel represent red, green, and 
blue; a value of 0 means that color is off, and the maximum value means that color is maxed out. 

Characters from a# to the next end-of-line are ignored (comments). 

N 0 line should be longer than 70 characters. 

H ereisan example of a small pixmap in thisformat: 

P3 

# feep.ppm 
4 4 
15 

000000000 15 0 15 
0000 15 7000000 
0000000 15 7000 
150 150 00 00 0000 


Programs that read thisformat should be as lenient as possible accepting anything that looks remotely like a pixmap. 
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There is also a variant on the format, available by setting the rawbits option at compile time. This variant is different in the 
following ways: 

The"magic number” is P6 instead of P3. 

Thepixel values are stored as plain bytes, instead of ASCII decimal. 

Whitespace is not allowed in the pixels area, and only a single character of whitespace (typically a newline) is allowed after 
themaxval. 

Thefiles are smaller and many times faster to read and write 

N otethat this raw format can only be used for maxvals less than or equal to 255 . If you use the ppm library and try to write a 
file with a larger maxval, it will automatically fall back on the slower but more general plain format. 

SEE ALSO 

giftoppm(l), gouldtoppm(l), ilbmtoppm(l), imgtoppm(l), mtvtoppm(l), pcxtoppm(l), pgmtoppm(l), piltoppm(l), picttoppm(l), 
pjtoppm(l), qrttoppm(l), rawtoppm(l), rgb3toppm(l), sldtoppm(l), spctoppm(l), sputoppm(l), tgatoppm(l), ximtoppm(l), 
xpmtoppm(l), yuvtoppm(l), ppmtoacad(l), ppmtogif(l), ppmtoicr(l), ppmtoilbm(l), ppmtopcx(l), ppmtopgm(l), ppmtopil(1), 
ppmtopict(l), ppmtopj(1), ppmtopuzz(l), ppmtorgb3(l), ppmtosixel(l), ppmtotga(l), ppmtouil(l), ppmtoxpm(l), ppmtoyuv(l), 
ppmdither(l), ppmforge(l), ppmhist(l), ppmmake(l), ppmpat(l), ppmquant(l), ppmquantall(l), ppmrelief(l), pnm(5), pgm(5), pbm(5) 

AUTHOR 

Copyright 1989,1991 byjef Poskanzer. 

27 September 1991 


I proc 

/proc— Process information pseudo-filesystem. 

DESCRIPTION 

/proc is a pseudo-filesystem that is used as an interface to kernel data structures rather than reading and interpreting / dev/ 
kmem. M ostof it is read-only, but some files allow kernel variablesto be changed. 

T he following outl ine gives a quick tour through the /proc hierarchy. 

[number ] There is a numerical subdirectory for each running process; the subdirectory is named by the 

process ID. Each contains the foil owing pseudo-files and directories, 
cmdiine This holds the complete command I ine for the process, unlessthewholeprocess has been swapped 

out or unless the process is a zombie. In either of these later cases, there is nothing in this file: That 
is, a read on thisfilewill return as having read 0 characters. T hisfile isnull-terminated but not 
newline-terminated. 

cwd This is a link current working directory of the process. To find outthecwd of process 20 , for 

instance, you can do this: cd /proc/ 20 /cwd; /bin/pwd. N otethat the pwd command is often a shell 
built in and might not work properly in thiscontext. 

environ T hisfile contains the environment for the process. T he entries are separated by null characters, and 

there may be a null character at the end. T hus, to print out the environment of process 1, you 
would do 

(cat /proc/1 /environ; echo) J tr 11 \000" “(n 11 
Fora reason why one should want to do this, seeiiio(8). 

exe A pointer to the binary that was executed and appears as a symbolic link. readiink(2) on theexe 

special file returns a string in the format: 

[devi ce ]:i node 

For example, [ 03011:1502 is inode 1502 on device major 03 (IDE, M FM, and so on drives), minor 



01 (first partition on the first drive). Also, the symbolic link can be dereferenced normally; 
attempting to open exe will open the executable You can even type /proc/[number ]/exe to run 
another copy of the same process as [number ]. 
find(l) with the -inum option can be used to locate the file. 

This is a subdirectory containing oneentry for each file that the process has open, named by its file 
descriptor, and that is a symbolic link to the actual file (as the exe entry does). Thus, 0 is standard 
input, 1 standard output, 2 standard error, and so on. 

Programs that will take a filename but will not take the standard input and that write to a file but 
will not send their output to standard output can be effectively foiled this way, assuming that -i is 
theflag designating an input file and -o istheflag designating an output file: 
foobar -i /proc/self/fd/0 -o /proc/self/fd/1 ... 

and you have a working filter. N otethat this will not work for programs that seek on their files 
because the files in thetd directory are not seekable. 

/proc/self/fd/N is approximately the same as /dev/fd/N in someU N IX and U NIX-1 ike systems. 

M ost Linux makedev scripts symbolically link /dev/fd to /proc/seif/fd, in fact. 

A file containing the currently mapped memory regions and their access permissions. 

The format is 


address 

per ms 

offset 

dev 

i node 

00000000 -0002f000 

r-x- 

00000400 

03:03 

1401 

0002f000-00032000 

rwx-p 

0002f400 

03:03 

1401 

00032000-0005b000 

rwx-p 

00000000 

00:00 

0 

60000000-60098000 

rwx-p 

00000400 

03:03 

215 

60098000-600C7000 

rwx-p 

00000000 

00:00 

0 

bfffa000-c0000000 

rwx-p 

00000000 

00:00 

0 


address is the address space in the process that it occupies, perms is a set of permissions r =read, w 
= write, x =execute, s =shared, p = private (copy on write). 

offset isthe offset into the fiie/what ever, dev isthe device (major: minor), and i node istheinode 
on that device. 0 indicates that no inode is associated with the memory region, as the case would be 
With bss. 

This is not the same as the mem (1,1) device, despite the fact that it has the same device numbers. 
The /dev/mem device is the physical memory before any address translation is done, but themem file 
here isthe memory of the process that accesses it. This cannot bemmap(2)ed currently, and will not 
be until ageneral mmap(2) isadded to the kernel. (Thismight have happened bythetimeyou read 
this) 

D i rectory of maps by mmap(2) that are symbolic links such as exe, fd /*, and so on. N otethat maps 
includes a superset of this information, so /proc/*/mmap should be considered obsolete. 

0 is usually iibc.so.4. 

/proc/*/mmap was removed in Linux kernel version 1.1.40. (It really was obsolete!) 

UNIX and Linux support the idea of a per-process root of the filesystem, set by thechroot(2) 
system call, root points to thefilesystem root and behaves asexe, fd/*, and so on do. 

Status information about the process. This is used by ps(l). T hefields, in order, with their proper 

scanf(3) format specifiers, are 

pid %d The process ID. 

comm %s Thefilenameof the executable in parentheses. This is visible whether or not 

the executable isswapped out. 



1176 


Part V: File Formats 


state %c 


ppid %d 
pgrp %d 
session %d 
tty %d 
tpgid %d 

flags %u 


minflt %u 

cminflt %u 
majflt %u 

cmajflt %u 
utime %d 
stime %d 
cutime %d 

cstime %d 

counter %d 

priority %d 

timeout %u 
itrealvalue %u 

starttime %d 
vsize %u 
rss %u 


rlim %u 
startcode %u 
endcode %u 
startstack %u 
kstkesp %u 

kstkeip %u 
signal %d 
blocked %d 


One character from thestring rsdzt where r is running, s issleeping in an 
interruptible wait, d issleeping in an uninterruptible wait or swapping, z is 
zombie, and t istraced or stopped (on asignal). 

ThePID of the parent. 

The process group ID of the process. 

ThesessionID oftheprocess. 

The tty the process uses. 

The process group ID of the process that currently owns the tty that the 
process is connected to. 

The flags of theprocess. Currently, every flag has the math bit set because 
crte.s checks for math emulation, so thisisnot included in the output. This 
is probably a bug because not every process is a compiled C program. The 
math bit should beadecimal 4, andthetraced bit is deci mal 10. 

T he number of minor faults the process has made, those that have not 
required loading a memory page from disk. 

The number of minor faults that the process and its children have made. 

The number of major faults the process has made those that have required 
loadi ng a memory page from disk. 

Thenumber of major faults that theprocess and its children havemade. 
Thenumber of jiffies that this process has been scheduled in user mode. 

The number of jiffies that this process has been scheduled in kernel mode. 
Thenumber of jiffies that thisprocess and its children have been scheduled 
in user mode. 

Thenumber of jiffies that thisprocess and its children have been scheduled 
in kernel mode. 

The current maximum size in jiffies of the process's next timeslice, or what is 
currently left of its current timeslice if it is the currently running process. 

The standard nice value plus fifteen. The value is never negative in the 
kernel. 

T he time in jiffies of the process's next timeout. 

The time (in jiffies) before the next sigalrm is sent to the process due to an 
interval timer. 

Time the process started in jiffies after system boot. 

Virtual memory size. 

Resident set size Number of pages the process has in real memory, minus3 
for administrative purposes. This is just the pages that count toward text, 
data, or stack space. This does not include pages that have not been demand- 
loaded in or that are swapped out. 

Current limit in bytes on therss of the process (usually 2 , 147 , 483 , 647 ). 
Theaddress above which program text can run. 

The address below which program text can run. 

T he address of the start of the stack. 

The current value of esp (32-bit stack pointer), as found in the kernel stack 
page for the process. 

The current eip (32-bit instruction pointer). 

T he bitmap of pendi ng signals (usually 0 ). 

The bitmap of blocked signals (usually 0,2 for shells). 
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cpuinfo 


devices 

dma 

filesystems 

interrupts 

ioports 

kcore 


kmsg 


ksyms 

loadavg 

malloc 

meminfo 


modules 

net 


arp 


sigignore %d T he bitmap of ignored signals, 

sigcatch %d T he bitmap of catched signals. 

wchan %u T his is the "channel" inwhich the process is waiti ng. T his is the address of a 

system call and can be looked up in a namelist if you need a textual name (If 
you have an up-to-date /etc/psdatabase, then try ps -1 to 9eethewcHAN field 
in action.) 

This is a collection of CPU and system architecture dependent items; for each supported architec¬ 
ture is a different list. The only two common entries are cpu, which istheCPU currently in use, 
and BogoMiPs, a system constant that is calculated during kernel initialization. 

T ext listing of major numbers and device groups. This can be used by makedev scripts for consis¬ 
tency with the kernel. 

This is a list of the registered ISA DMA (direct memory access) channels in use. 

A text listing of the filesystems that were compiled into the kernel. Incidentally, this is used by 
mount(l) to cyclethrough different filesystems when none isspecified. 

This is used to record the number of interrupts per each IRQ on (at least) thei386 architecture. 
Very easy to read formatting done in ASCII. 

T his is a list of currently registered input-output port regionsthat are in use. 

Thisfile represents thephysical memory of the system and is stored in thecore file format. With 
this pseudo-file and an unstripped kernel (/usr/src/iinux/toois/zsystem) binary, gdb can be used 
to examine the current state of any kernel data structures. 

Thetotal length of thefile is the size of physical memory (RAM ) plus 4K B. 

This file can be used instead of thesysiog(2) system call to log kernel messages. A process must 
have superuser privileges to read thisfile, and only one process should read thisfile. T hisfileshould 
not be read if a sysiog process is running that uses the sysiog(2) system call facility to log kernel 
messages. 

Information in thisfile isretria/ed with thedmesg(8) program. 

This holds the kernel exported symbol definitions used by the modules (X) toolsto dynamically link 
and bind loadable modules. 

The load average numbers give the number of jobs in the run queue averaged over 1, 5, and 15 
minutes. They are the same as the load average numbers given by uptime(l) and other programs. 

T his file is only present if configdebugmalloc was defined during compilation. 

This is used by free(l) to report the amount of free and used memory (both physical and swap) on 
the system as well as the shared memory and buffers used by the kernel. 

It is in the same format as tree(l) except in bytes rather than KB. 

A text list of the modules that have been loaded by the system. 

Various net pseudo-files, all of which give the status of some part of the networking layer. These 
files contain ASCII structures and are therefore readable with cat. H owever, the standard 
netstat(8) suite provides much cleaner access to these files. 

This holds an ASCII readable dump of the kernel ARP table used for address resolutions. It will 
show both dynamically learned and pre-programmed ARP entries. The format is 


IP address 

HW type 

Flags 

HW address 

10.11.100.129 

0x1 

0x6 

00:20:8A:00:0C:5A 

10.11.100.5 

0x1 

0x2 

00:C0:EA:00:00:4E 

44.131.10.6 

0x3 

0x2 

GW4PTS 


i p address isthe IPv4 address of the machi ne. T he hw type is the hardware type of the address from 
RFC 826. T he flags are the internal flags of the AR P structure (as defined in /usr/inciude/iinux/ 
if arp. h) and the hw address isthe physical layer mapping for that IP address if it is known. 
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dev 


ipx 

ipx_route 

rarp 

raw 

route 

snnp 

top 

udp 


unix 


The dev pseudo-file contains network device status information. This gives the number of received 
and sent packets, the number of errors and collisions, and other basic statistics. T hese are used by 
the if conf ig(8) program to report device status. The format is 

Inter-j Receive | Transmit 

face |packets errs drop fifo frame|packets errs drop fifo colls carrier 
lo: 0 0 0 0 0 2353 0 0 0 0 0 

eth0: 644324 1001 563770 0 0 0 581 0 

No information. 

No information. 

Thisfileusesthesameformat astheARP fileand contains the current reverse mapping database 
used to provide rarp(8) ra/erse address lookup services. If rarp is not configured into the kernel, 
thisfilewill not be present. 

H olds a dump of the RAW socket table. M uch of the information is not of use apart from 
debugging. The si value is the kernel hash slot for the socket; theiocai_address isthe local address 
and protocol number pair, st istheinternal status of the socket. The tx_queue and rx_queue are the 
outgoing and incoming data queue in terms of kernel memory usage. The tr, tm->when, and rexmits 
fields are not used by RAW. Theuid field holds the creator euid of the socket. 

No information but looks similar to route(8). 

This file holds the ASCI I data needed for the IP, 1C M P, TCP, and U D P management information 
bases for an smp agent. Asofwriting, theTCP mib is incomplete. It should be completed by 1.2.0. 
HoldsadumpoftheTCP socket table. M uch of the information is not of use apart from 
debugging. The si value isthe kernel hash slot for the socket; theiocai_address isthe local address 
and port number pair. The remote_address is the remote address and port number pair (if 
connected), st istheinternal status of the socket. The tx_queue and rx_queue are the outgoing and 
incoming data queue in termsof kernel memory usage. The tr, tm->when, and rexmits fields hold 
internal Information of the kernel socket state and are only useful for debugging. Theuid field 
holds the creator euid of the socket. 

H olds a dump of the U D P socket table. M uch of the information is not of use apart from 
debugging. The si value isthe kernel hash slot for the socket; theiocai_address isthe local address 
and port number pair. The remote^address is the remote address and port number pair (if 
connected), st istheinternal status of the socket. The tx_queue and rx_queue are the outgoing and 
incoming data queue in termsof kernel memory usage. The tr, tm->when, and rexmits fieldsarenot 
used by U DP. Theuid field holds the creator euid of the socket. The format is 

sl local_address rem_address st tx_queue rx_queue tr rexmits tm->when uid 

1: 01642089:0201 0C642C89:03FF 01 00000000:00000001 01:000071BA 00000000 0 

1: 00000000:0801 00000000:0000 0A 00000000:00000000 00:00000000 6F000100 0 

1: 00000000:0201 00000000:0000 0A 00000000:00000000 00:00000000 00000000 0 

Liststhe U N IX domain sockets present within thesystem and their status. Theformat is 

Num RefCount Protocol Flags Type St Path 

0: 00000002 00000000 00000000 0001 03 

1: 00000001 00000000 00010000 0001 01 /dev/printer 

Num isthe kernel table slot number, Retcount isthe number of users of the socket, Protocol is 
currently always 0 , and Flags represents the internal kernel flags holding the status of the socket. 
Type is currently always 1 (UNIX domain datagram sockets are not yet supported in the kernel), st 
istheinternal state of the socket and Path isthe bound path (if any) of the socket. 



pci 

scsi 


scsi/scsi 


drivername 


self 

stat 

cpu 3357 0 4313 

disk 0000 

page 5741 1808 
swap 1 0 
intr 1462898 
ctxt 115315 
btime 769041601 
sys 


kernel 


/proc 



This is a listing of all PCI devices found during kernel initialization and their configuration. 

A directory with the SC SI mid-level pseudo-file and various SC SI low-level driver directories, 
which contain a file for each SCSI host in this system, all of which give the status of some part 
oftheSCSI 10 subsystem. These files contain ASCI I structures and are therefore readable with 
cat. 

You can also write to some of the files to reconfigure the subsystem or switch certain features on 
or off. 

This is a listing of all SCSI devices known to the kernel. The listing is similar to the one seen 
during bootup, scsi currently supports only the single device command, which allows root to 
add a hot-plugged device to the list of known devices. 

An echo 1 scsisingledevicel 0 5 0'> /proc/scsi/scsi Will Cause host scsil to Scan On SC SI 
channel 0 foradeviceon ID 5 LUN 0.1 f there is already a da/ice known on this address or the 
address is invalid, an error will be returned. 

drivername Can Currently beNCR53c7xx, aha152x, aha1542, aha1740, aic7xxx, buslogic, eata_dma, 
eata_pio, fdomain, in2000, pas16, qlogic, scsi_debug, Seagate, 1128, u15-24f, ultrastor, Or 

wd7000. These directories show up for all drivers that registered at least one SC SI H BA. Every 
directory contains one file per registered host. Every host-file is named after the number the 
host got assigned during initialization. 

Reading these files will usually show driver and host configuration, statistics, and so on. 

Writing to these files allows different things on different hosts. For example, with the latency 
and noiatency commands root can switch on and off command latency measurement code in 
the eata_dma driver. W ith the lockup and unlock commands, root can control bus lockups 
simulated by thescsi_debug driver. 

This directory refers to the process accessing the /proc filesystem and is identical to the / proc 
directory named by the process ID of the same process, 
kernel/system Statistics. 

1362393 The number of jiffies (l/100ths of a second) that the system spent in user mode, user mode 

with low priority (nice), system mode, and the idle task. The last value should be 100 times the 
second entry in the uptime pseudo-file 

The four disk entries are not implemented at this time I'm not even sure what this should be 
because kernel statistics on other machines usually track both transfer rate and I/O s per second 
and thisonly allows for onefi eld per drive. 

T he number of pages the system paged in and the number that were paged out (from disk). 

The number of swap pages that have been brought in and out. 

The number of interrupts received from the system boot. 

The number of context switches that the system underwent. 

Boottimein seconds si nee the epoch (January 1,1970). 

This directory (present since 1.3.57) contains a number of files and subdirectories correspond¬ 
ing to kernel variables. These variables can be read and sometimes modified using theproc 
filesystem and using the syscti(2) system call. Presently, there are subdirectories kernel, net, 
and vm that each contain more files and subdirectories. 

This Contains the files domainname, file-max, file-nr, hostname, inode-max, inode-nr, osrelease, 
ostype, panic, real-root-dev, securelevel, and version, with function fairly Clear from the 
name 

The (read-only) file file-nr gives the number of files presently opened. The file file-max gives 
the maxi mum number of open files the kernel is willing to handle. If 1024 is not enough for 
you, try echo 4096 > /proc/sys/kernel/file-max. 

Similarly, the files inode-nr and inode-max indicate the present and the maximum number of 
inodes. 
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T he files ostype, osrelease, and version give substrings Of /proc/version. 

The file panic gives r/w access to the kernel variable panic_timeout. If this is zero, the kernel will 
loop on a panic; if nonzero, it indicates that the kernel should autoreboot after this number of 
minutes. 

Thefilesecureievei seems rather meaningless at present; root is just too powerful, 
uptime Thisfilecontainstwo numbers: theuptimeof thesystem (seconds) and the amount of time 

spent in idle process (seconds). 

version This string identifies the kernel version that is currently running. For instance: 

Linux version 1.0.9 (quinlan@phaze) #1 Sat May 14 01:51:54 EDT 1994 

SEE ALSO 

cat(l), find(l), free(l), mount(l), ps(l), tr(l), uptime(l), readlink(2), mmap(2), chroot(2), syslog(2), hier(7), arp(8), 
dmesg(8), netstat(8), route(8), ifconfig(8), procinfo(8) and much more 

C0NF0RMST0 

This roughly conforms to a Linux 1.3.11 kernel. PI ease update this as necessary! Last updated for Linux 1.3.11. 

CAVEATS 

N otethat many strings (the environment and command line) are in the internal format, with subfields terminated by null 
bytes, so you mightfindthatthingsaremorereadableifyouuseod -cortr "\ 000 " ■\n" to read them. 

This manual page is incomplete, possibly inaccurate, and isthekind of thing that needs to be updated very often. 

BUGS 

The / proc filesystem may introduce security holes into processes running with chroot(2). For example, if /proc is mounted in 
thechroot hierarchy, achdir(2) to /proc/ 1 /root will return to the original root of the filesystem. This may be considered a 
feature instead of a bug because Linux does not yet support the fchroot(2) call. 

22 July 1996 
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protocols—The protocols definition file 


DESCRIPTION 

Thisfileisaplain ASCII file, describing the various DAR PA Internet protocols that are avail able from the TCP/IP 
subsystem. It should be consulted instead of using the numbers in the ARP A include files or, even worse, just guessing them. 
These numbers will occur in the protocol field of any IP header. 

Keep thisfile untouched because changes would result in incorrect IP packages. Protocol numbers and names are specified by 
the D D N N etwork I nformation C enter. 

Each line is of the following format: 

protocol number aliases ... 

The fields are delimited by spaces or tabs. Empty lines and lines starting with a hash mark (#) are ignored. Remainder of lines 
are also ignored from the occurrence of a hash mark. 

Thefield descriptions are 

protocol The native name for the protocol—for example, ip, tcp, orudp. 

number T he official number for this protocol asitwill appearwithin thelP header, 

ai i ases Optional aliases for the protocol. 
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This file might be distributed over a network using a network-wide naming service such as Yellow Pages/N IS or BIND/ 

H esoid. 

FILES 

/etc/protocois T he protocols definition file. 

SEE ALSO 

getprotoent(3), GuidetoYellow P ages Servi ce, Guide to BIN D/Hesiod Service 

Linux, 18 October 1995 
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rcsfile— Format of RCS file 

DESCRIPTION 

An RCS file's contents are described by the grammar below. 

The text is free format: space, backspace tab, newline, vertical tab, form feed, and carriage return (collectively, whitespace) 
have no significance except in strings. H owever, whitespace cannot appear within an ID, num, or sym, and an RCS file must 
end with a newline. 

Strings are enclosed by?. If a string contains a?, it must be doubled; otherwise strings can contain arbitrary binary data. 

T he meta syntax uses the following conventions: | (bar) separates alternatives; { and } enclose optional phrases. { and }* 
enclose phrases that can be repeated zero or more times. { and {+ enclose phrases that must appear at least once and can be 
repeated. Terminal symbols are in boldface; non-terminal symbols are in italics. 

rcstext ::= admin {delta}* desc {del tatext }* 
ad mi n : := head {num}; 

{ branch {num}; } 

access {id}*; 

symbol s {sym : num}*; 

locks {id : num}*; {strict ;} 

{ comment {string}; } 

{ expand {string}; } 

{ newphrase }* 
delta : := num 

date num; 
author id; 
state {id}; 
branches {num}*; 
next {num}; 

{ new- phrase }* 
desc : := desc string 
del tatext : := num 

log string 
{ newphr as e }* 
text string 
num : := {digit \ .}+ 

di gi t ::= 0 | 1 j 2 | 3 j 4 | 5 | 6 j 7 | 8 j 9 

id ::= {num} idchar {idchar | num}* 

sym ::= {digit}* idchar {idchar j digit}* 

idchar ::= any visible graphic character except special 

special : := $ | , \ . j : [ ; | @ 

string ::= @{any character, with @doubled}*@ 
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newphrase ::= i d word* ; 
word : := i d | niim | string j : 

Identifiers are case sensitive. Keywords arein lowercase only. The sets of keywords and identifiers can overlap. In most 
environments, RCS uses the I SO 8859/1 encoding: visible graphic characters are codes 041-176 and 240-377, and 
whitespace characters are codes 010-015 and 040. 

Dates, which appear after the date keyword, are of the form Y.mm.dd.hh.mm.ss, where Y is the year, mm the month (01-12), 
dd the day (01-31), hh the hour (00-23), mm the minute (00-59), and ssthe second (00-60). Y contains just the last two 
digits of the year for years from 1900 through 1999, and all the digits of years thereafter. Dates use the Gregorian calendar; 
times useUTC. 

The newphrase productions in the grammar are reserved for future extensions to the format of RCS files. N o newphrase will 
begin with any keyword already in use. 

The delta nodes form a tree. All nodes whose numbers consist of a single pair (such as 2.3, 2.1,1.3, and so on) are on the 
trunk and are linked through the next field in order of decreasing numbers. The head field in the admin node points to the 
head of that sequence (contains the highest pair). The branch node in the admin node indicates the default branch (or 
revision) for most RCS operations If empty, the default branch is the highest branch on the trunk. 

All delta nodes whose numbers consist of 2 n fields (n2) (such as 3.1.1.1, 2.1.2.2, and so on) are linked as follows. All nodes 
whose first 2n-l number fields are identical are linked through thenext field in order of increasing numbers. For each such 
sequence, the delta node whose number is identical to the first 2n-2 number fields of the deltas on that sequence is cal led 
the branchpoint. The branches field of a node contains a list of the numbers of the first nodes of all sequences for which it is 
a branchpoint. T his list is ordered in increasing numbers. 

Thefollowing diagram shows an exampleof an RCS file's organization. 
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IDENTIFICATION 

Author: Walter F. Tichy, Purdue University, W est Lafayette, IN, 47907. M anual Page Revision: 5.6; Release Date: 1995/ 
06/05. Copyright 1982,1988,1989, Walter F. Tichy. Copyright 1990,1991,1992,1993,1994,1995, Paul Eggert. 


SEE ALSO 

rcsintro(l), ci(l), co(l), ident(l), res( 1) , rcsclean(l), rcsdiff(l), rcsmerge(l), rlog(l), W alter F. Tichy, RC S, "A System 
for Version Control," Software - Practice & Experience, 15, 7 (July 1985), 637-654. 

GNU, 5Junel995 


resolver 

resolver— Resolver configuration file. 

SYNOPSIS 

/etc/resolv.conf 

DESCRIPTION 

The resolver is a set of routines in theC library (re soiv(3)) that provides access to the Internet Domain N ame System. The 
resolver configuration file contains information that is read by the resolver routines thefirst time they are invoked by a 
process. The file is designed to be human readable and contains a list of keywords with values that provide various types of 
resolver information. 

On a normally configured system, thisfile should not be necessary. The only nameserver to be queried will be on the local 
machine, the domain name is determined from the host name, and the domain search path is constructed from the domain 
name. 

T he different configuration options are 

nameserver Internet address (in dot notation) of a nameserver that the resolver should query. Up to 

maxns (currently 3) nameservers may be listed, one per keyword. If there are multiple servers, 
the resolver library queries them in the order listed. If no nameserver entries are present, the 
default is to use the nameserver on the local machine. (The algorithm used is to try a 
nameserver, and if the query times out, try the next until you run out of nameservers, and 
then repeat trying all the nameservers until a maximum number of retries are made) 
domain Local domain name. M ost queries for names within thisdomain can use short names 

relative to the local domain. If no domain entry is present, the domain is determined from 
the local hostname returned by gethostname(2); the domain part is taken to be everything 
after thefirst.. Finally, if the hostname does not contain a domain part, the root domain is 
assumed. 

search Search list for hostname lookup. T he search list is normally determi ned from the local 

domain name; by default, it contains only the local domain name This may be changed by 
listing thedesired domain search path following the search keyword with spaces or tabs 
separating the names. M ost resolver queries will be attempted using each component of the 
search path in turn until a match isfound. N otethat this process may be slow and will 
generate a lot of network traffic if the servers for the listed domains are not local and that 
queries will timeout if no server isavailablefor one of the domains. 

Thesearch list is currently limited to sixdomainswith a total of 256 characters, 
sortust sortiist allows addresses returned by gethostbyname to be sorted. A sort list is specified by 

IP address netm ask pairs. The netmask is optional and defaults to the natural netmask of 
the net. The IP address and optional network pairs are separated by slashes. Up to 10 pairs 
may be specified. 


sortiist 130.155.160.0/255.255.240.0 130.155.0.0 
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options options allows certain internal resolver variables to be modified. The syntax is 

options option ... 
where o pt i on is one of the following: 
debug SGtS RESDEBUG in res.options. 

ndots :n sets a threshold for the number of dots that must appear in a name given to 
res_query (see resoiver(3)) before an initial absolute query will be made. The default for n is 
i, meaning that if there are any dots in a name, the name will be tried first as an absolute 
name before any search list elements are appended to it. 

The domain and search keywords are mutually exclusive. If more than one instance of these keywords is present, the last 
instance wins 

The search keyword of a system's resoiv.conf file can be overridden on a per-process basis by setting the environment 
variable localdomain to a space-separated list of search domains. 

The options keyword of a system's resoiv.conf file can be amended on a per-process basis by setting the environment 
variable res_options to a space-separated list of resolver options as explained previously. 

The keyword and value must appear on a single line, and the keyword (such asnameserver) must start the line. The value 
follows the keyword, separated by whitespace. 

FILES 

/etc/resolv.conf 

SEE ALSO 

gethostbyname(3), resolver(3), hostname(7), named(8), N ameServer 0 perationsG uidefor BIND 

11 November 1993 
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securetty— File that lists ttys from which root can log in. 

DESCRIPTION 

/etc/securetty is used by iogin(l); the file contains the device names of tty lines (one per line, without leading /dev/) on 
which root is allowed to log in. 

FILES 

/etc/securetty 


SEE ALSO 

login(l) 


Linux, 29 December 1992 
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services— Internet network services list. 

DESCRIPTION 

services isa plain ASCII file providing a mapping between friendly textual names for Internet services and their underlying 
assigned port numbers and protocol types. Every networking program should look into this file to get the port number (and 



services 


protocol) for its service. T he C library routines getservent(3), getservbyname(3), getservbyport(3), setservent(3), and 
endservent(3) support querying this file from programs. 

Port numbers are assigned by the IAN A (Internet Assigned N umbers Authority), and their current policy is to assign both 
TCP and U D P protocols when assigning a port number. Therefore, most entries will have two entries, even for TCP-only 
services. 

Port numbers below 1024 (so-called low-numbered ports) can only be bound to by root (seebind(2), tcp(7), and udp(7).) 
This is so that clients connecting to low-numbered ports can trust that the service running on the port isthe standard 
implementation and not a rogue service run by a user of the machine. W ell-known port numbers specified by the I AN A are 
normally located in this root-only space. 

The presence of an entry for a service in the services file does not necessarily mean that the service is currently running on 
the machine. Seeinetd.cont(5) for the configuration of Internet services offered. N otethat not all networking services are 
started by inetd(8) and so won't appear in inetd.conf(5). In particular, news (N NT P) and mail (SM TP) servers are often 
initialized from the system boot scripts. 

The location Of the services file is defined by PATH SERVICES in /usr/include/netdb.h. This is usually set to /etc/services. 
Each line describes one service and isoftheform: 

service-name port /protocol [aliases ...] 

service- name Thefriendly nametheserviceisknown by and looked up under. It is case sensitive. Often, 

the client program is named after the servi ce - name, 
port The port number (in decimal) to use for this service. 

protocol Thetypeof protocol to beused. This field should match an entry in theprotocois(5) file. 

Typical values include tcp and udp. 

aliases An optional space- or tab-separated list of other names for this service (see the Bugs section 

below). Again, the names are case sensitive. 

Either spaces or tabs may beused to separate the fields. 

Comments are started by the hash sign (#) and continue until the end of the line Blank lines are skipped. 

Theservi ce-name should begin in the first column of the file because leading spaces are not stripped, servi ce- names can be 
any printable characters excluding space and tab; however, a conservative choice of characters should beused to minimize 
inter-operability problems. For example, a-z, 0-9, and hyphen (-) would seem a sensible choice 

Linesnotmatchingthisformat should not be present in thefile. (Currently, they are silently skipped by getservent(3), 
getservbyname(3), and getservbyport(3). H owever, this behavior should not be relied on.) 

Asa backwards compatibility feature, the slash (/) between the port number and protocol name can in fact be either a slash 
oracomma(,). Use of the comma in modern installations is depreciated. 

This file might be distributed over a network using a network-wide naming service such as Yellow Pages/N IS or BIND/ 

H esiod. 

A sample services file might look like this 


netstat 

15/tcp 


qotd 

17/tcp 

quote 

msp 

18/tcp 

# message send protocol 

msp 

18/udp 

# message send protocol 

chargen 

19/tcp 

ttytst source 

chargen 

19/udp 

ttytst source 

ftp 

21 /tcp 


# 

22 - unassigned 

telnet 

23/tcp 
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BUGS 

There is a maximum of 35 aliases, due to the way thegetservent(3) code is written. 

Lines longer than bufsiz (currently 1024 ) characters will be ignored by getservent(3), getservbyname(3), and 
getservbyport(3). H owever, this will also cause the next lineto bemisparsed. 

FILES 

/etc/services The Internet network services list 

/usr/include/netdb.h Definition Of_PATH_SERVICES 

SEE ALSO 

getservent(3), getservbyname(3), getservbyport(3), setservent(3), endservent(3), protocols(5), listen(2), inetd.conf(5), 
inetd(8), Assigned N umbers RFC, most recently RFC 1700 (AKA STD 0002), Guide to Yellow Pages Service, Guide to 
BIN D/H esiod Service. 

Linux, 11 January 1996 
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shells— Pathnamesof valid login shells 

DESCRIPTION 

/etc/sheiis is a text filethat contains the full pathnamesof valid login shells. T his file is consulted bychsh(l) and is available 
to be queried by other programs. 

EXAMPLES 

/etc/sheiis may contain the following paths: 

/bin/sh 

/bin/csh 

FILES 

/etc/shells 


SEE ALSO 

chsh(l) 


21 November 1993 
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sysiog.cont— sysiogd(8) configuration file. 

DESCRIPTION 

The syslog.conf file is the configuration file for the sysiogd(8) program. It consists of lines with two fields: the selector 
field, which specifies the types of messages and priorities to which theline applies, and an action field, which specifies the 
action to betaken if a message sysiogd received matches the selection criteria. There cannot beany spaces in the action field. 
T he selector field isseparated from the action field by one or more tab or space characters. (This is a departure from the 
standard BSD way of doing things; both tabs and spaces can beusedto separate the selector from the action.) 

The selector functions are encoded as a facility, a period (.), and a level, with no intervening whitespace. Both the facility 
and the level are case insensitive. 



s/slog, con f 

The facility describes the part of the system generating the message and is one of the following keywords: auth, authpriv, 
cron, daemon, kern, lpr, mail, mark, news, syslog, user, uucp, and local 0 through local7. T hese keywords (with the exception 
of mark) correspond to the similar dv log_ values specified to the openiog(3) and sysiog(3) library routines. 

T he level describes the severity of the message and isa keyword, optionally preceded by an equals (=), from the following 
ordered list (higher to lower): emerg, alert, crit, err, warning, notice, info, and debug. T hese keywords correspond to the 
similar dv log_ values specified to thesysiog library routine. 

See sysiog(3) for further descriptions of both thefaciiity and level keywords and their significance. 

If a received message matches the specified facility and is of the specified level (or a higher level if level was specified without 
=), theaction specified in the action field will betaken. 

M ultiple selectors may be specified for a single action by separating them with semicolon (;) characters. It is important to 
note howa/er, that each selector can modify the ones preceding it. 

M ultiple facilities may be specified for a single level by separating them with comma (,) characters. 

An asterisk (*) can be used to specify all facilities or all levels. 

The special facility "mark" receives a message at priority "info" every 20 minutes (seesysiogd(8)). This is not enabled by a 
facility field containing an asterisk. 

The special level "none” disables a particular facility. 

Theaction field of each line specifies the action to betaken when the selector field selects a message. There are four forms: 
A pathname (beginning with a leading slash). Selected messages are appended tothefile. 

A hostname (preceded by an at (@) sign). Selected messages are forwarded to thesysiogd program on the named host. 

A comma-separated list of users. Selected messages are written to those users if they are logged in. 

An asterisk. Selected messages are written to all logged-in users. 

Blank lines and lines whose first non-blank character isa hash (#) character are ignored. 

EXAMPLES 

A configuration file might appear as follows: 

# Log all kernel messages, authentication messages of 

# level notice or higher and anything of level err or 

# higher to the console. 

# Don't log private authentication messages! 

*.err;kern.*;auth.notice;authpriv.none /dev/console 

# Log anything (except mail) of level info or higher. 

# Don't log private authentication messages! 

*.info;mail.none;authpriv.none /var/log/messages 

# Log debug messages only 

*.=debug /var/log/debug 

# The authpriv file has restricted access. 

authpriv.* /var/log/secure 

# Log all the mail messages in one place. 

mail.* /var/log/maillog 

# Everybody gets emergency messages, plus log them on another 

# machine. 



.emerg 

.emerg 


@arpa.berkeley.edu 
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# Root and Eric get alert and higher messages. 

*.alert root,eric 

# Save mail and news errors of level err and higher in a 

# special file. 

uucp,news.crit /var/log/spoolerr 

FILES 

/etc/sysiog.conf The sysiogd(8) configuration file. 

BUGS 

The effects of multiple selectors are sometimes not intuitive. For example mail. crit,*. err will select mail facility messages at 
the level of err or higher, not at the level of crit or higher. 

SEE ALSO 

syslog(3), syslogd(8) 

10 May 1991 
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termcap— Terminal capability database. 

DESCRIPTION 

The termcap database is an obsolete facility for describing the capabilities of character-cell terminals and printers. It is 
retained only for capability with old programs; new ones should usetheterminfo(5) database and associated libraries. 

/etc/termcap is an ASCII file (the database master) that lists the capabilities of many different types of terminals. Programs 
can read termcap to find the particular escape codes needed to control the visual attributes of the terminal actually in use. 
(Other aspects of the terminal are handled by stty.) The termcap database is indexed on the term environment variable. 

termcap entries must be defined on a single logical line with \ used to suppress the newline. Fields are separated by :. The 
first field of each entry starts at the I eft-hand margin and containsa list of names for the terminal, separated by . 

The first subfield may (in BSD termcap entries from versions 4.3 and prior) contain a short name consisting of two 
characters. T his short name may consist of capital or small letters. In 4.4 BSD termcap entries, this field is omitted. 

The second subfield (first in the newer 4.4 BSD format) contains the name used by the environment variableTERM. It should 
be spelled in lowercase letters. Selectable hardware capabilities should bemarked by appending a hyphen and a suffix to this 
name. U sual suffixes are w (more than 80 characters wide), am (automatic margins), nam (no automatic margins) and rv 
(reverse video display). The third subfield containsa long and descriptive name for this termcap entry. 

Subsequent fields contain the terminal capabilities; any continued capability lines must be indented one tab from the left 
margin. 

Although there is no defined order, it is suggested to write first Boolean, then numeric, and at last string capabilities, each 
sorted alphabetically without looking at lower or upper spelling. Capabilities of similar functions can be written in one line. 

Example: 

Head line: vt|vt101|DEC VT 101 terminal in 80 character mode:\ 

Head line: Vt[vt101-w|DEC VT 101 terminal in (wide) 132 character mode:\ 

Boolean: :bs:\ 

Numeric: :co#80:\ 

String: :sr=nE[H:\ 
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Boolean Capabilities 


5i 

Printer will not echo on screen 

am 

Automatic marginswhich means automatic linewrap 

bs 

Ctrl+H (8 dec.) performs a backspace 

bw 

Backspaceon left margin wraps to previous line and right margin 

da 

D isplay retained above screen 

db 

D isplay retained below screen 

eo 

A space erases all characters at cursor position 

es 

Escape sequences and special characters work in status line 

gn 

Generic device 

he 

This is a hardcopy terminal 

HC 

The cursor is hard to see when not on bottom line 

hs 

Has a status line 

hz 

H azeltine bug; theterminal cannot print tilde characters 

in 

Terminal inserts nulls, not spaces, to fill whitespace 

km 

Terminal has a meta key 

mi 

Cursor movement works in insert mode 

ms 

C ursor movement works in standout/underline mode 

NP 

N o pad character 

NR 

ti does not reverse te 

nx 

No padding; mustuseXON/XOFF 

os 

Terminal can overstrike 

ul 

Terminal underlines, although it cannot overstrike 

xb 

Beehive glitch; FI $nds Escape and F2 sends “C 

xn 

N ewlin^wraparound glitch 

xo 

Terminal usesXON/XOFF protocol 

xs 

Text typed over standout text will be displayed in standout 

xt 

T eleray glitch; destructive tabs and odd standout mode 

NumericCapabilities 

CO 

Number of columns 

dB 

Delay in mi Hi seconds for backspace on hardcopy terminals 

dC 

Delay in mi Hi seconds for carriage return on hardcopy terminals 

dF 

Delay in mi Hi seconds for form feed on hardcopy terminals 

dN 

Delay in millisecondsfor newlineon hardcopy terminals 

dT 

Delay in millisecondsfor tabulator stop on hardcopy terminals 

dV 

Delay in millisecondsfor vertical tabulator stop on hardcopy terminals 

it 

D ifference between tab positions 

lh 

Height of soft labels 

lm 

Linesof memory 

lw 

Width of soft labels 


continues 
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N umericCapabilities 


li 

N umber of lines 

N1 

N umber of soft labels 

pb 

Lowest baud rate that needs padding 

sg 

Standout glitch 

ug 

Underline glitch 

vt 

Virtual terminal number 

ws 

Width of status line if different from screen width 

StringCapabilities 

! 1 

Shifted save key 

!2 

Shifted suspend key 

!3 

Shifted undo key 

#1 

Shifted help key 

#2 

Shifted home key 

#3 

Shifted input key 

#4 

Shifted cursor left key 

%0 

Redo key 

%1 

H elp key 

%2 

M ark key 

%3 

M essage key 

%4 

M ove key 

%5 

N ext-object key 

%6 

Open key 

%7 

Options key 

%8 

Previous-object key 

%9 

Print key 

%a 

Shifted message key 

%b 

Shifted move key 

%c 

Shifted next key 

%d 

Shifted options key 

%e 

Shifted previous key 

%f 

Shifted print key 

%g 

Shifted redo key 

%h 

Shifted replace key 

%i 

Shifted cursor right key 


Shifted resume key 

&0 

Shifted cancel key 

&1 

Reference key 

&2 

Refresh key 

&3 

Replace key 

&4 

Restart key 
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65 

66 

67 

68 
&9 
*0 
*1 
*2 
*3 
*4 
*5 
*6 
*7 


*9 

@0 

@1 

02 

03 

@4 

05 

@6 

07 

08 

@9 

al 

AL 

ac 

ae 

as 

be 

bl 

bt 

cb 

cc 

cd 

ce 

ch 

cl 

cm 

CM 


Resume key 
Save key 
Suspend key 
U ndo key 
Shifted begin key 
Shifted find key 
Shifted command key 
Shifted copy key 
Shifted create key 
Shifted delete character 
Shifted delete line 
Select key 
Shifted end key 
Shifted clear line key 
Shifted exit key 
Find key 
Begin key 
C ancel key 
Close key 
Command key 
Copy key 
C reate key 
End key 
Enter/send key 
Exit key 
Insert one line 
Insert%i lines 

Pairs of block graphic characters to map alternate character set 
End alternative character set 

Start alternative character set for block graphic characters 
Backspace if not “H 
Audio bell 

M oveto previous tab stop 
Clear from beginning of line to cursor 
D ummy command character 
Clear to end of screen 
Clear to end of line 

M ove cursor horizontally only to column %i 

C lear screen and cursor home 

Cursor move to row %i and column %2 (on screen) 

M ove cursor to row %i and column %2 (in memory) 


continues 
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cr 

cs 

ct 

cv 

dc 

DC 

dl 

DL 

dm 

do 

DO 

ds 

eA 

ec 

ed 

ei 

ff 

fs 

FI 

F2 

F3 


Carriage return 

Scroll region from line%i to %2 
Clear tabs 

M ove cursor vertically only to line %i 

Delete one character 

Delete%i characters 

Delete one line 

Delete%i lines 

Begin delete mode 

Cursor down one line 

Cursor down #1 lines 

D isable status line 

E nable alternate character set 

E rase %i characters starting at cursor 

End delete mode 

End insert mode 

Formfeed character on hardcopy terminals 
Return character to its position before going to status line 
T he string sent by function keyfll 
T he string sent by function key fl2 
T he string sent by function key f!3 


F9 T he string sent by function key fl9 

fa T he string sent by function key f20 

fb The string sent by function key f21 


fz T he string sent by function key f45 

Fa T he string sent by function key f46 

Fb T he string sent by function key f47 


Fr 

The string sent by function key f63 

hd 

M ove cursor a half line down 

ho 

Cursor home 

hu 

Move cursor a half lineup 

il 

Initialization string 1 at login 

i3 

Initialization string 3 at login 

is 

Initialization string 2 at login 

ic 

Insert one character 

IC 

Insert%i characters 

if 

Initialization file 

im 

Begin insert mode 
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ip 

iP 

K1 

K2 

K3 

K4 

K5 

k0 

kl 

k2 

k3 

k4 

k5 

k6 

k7 

k8 

k9 

k; 

ka 

kA 

kb 

kB 

kC 

kd 

kD 

ke 

kE 

kF 

kh 

kH 

kl 

kl 

kL 

kM 

kN 

kP 

kr 

kR 

ks 

kS 

kt 


Insert pad timeand needed special characters after insert 

Initialization program 

U pper-left key on keypad 

Center key on keypad 

U pper-right key on ke/pad 

Bottom-left ke/ on ke/pad 

Bottom-right key on keypad 

Function key 0 

Function key 1 

Function key 2 

Function key 3 

Function key 4 

Function key 5 

Function key 6 

Function key 7 

Function key 8 

Function key 9 

Function key 10 

Clear all tabs key 

Insert line key 

Backspace ke/ 

Back tab stop 
Clear screen key 
Cursor down key 

Key for delete character under cursor 

T urn keypad off 

Key for clear to end of line 

K ey for scrolli ng forward/down 

Cursor home key 

Cursor down key 

Insert character/insert mode key 

Cursor left key 

Key for delete line 

Key for exit insert mode 

Key for next page 

Key for previous page 

Cursor right key 

Key for scrolling backward/up 

T urn keypad on 

Clear to end of screen key 

Clear this tab key 


continues 



Part V: File Formats 



StringCapabilities 

kT 

ku 

10 

11 

12 

la 

le 

11 

LE 

LF 

LO 

mb 

MC 

md 

me 

mh 

mk 

ML 

mm 

mo 

mp 

mr 

MR 

nd 

nw 

pc 

Pf 

pk 

Pi 

pn 

po 

pO 

ps 

px 

rl 

r2 

r3 

RA 

rc 

rf 


Set tab here key 
Cursor up key 

Label of zeroth function key, if not fO 
Label of first function key, if notfl 
Label of first function key, if not f2 

Label of tenth function key, if notflO 

Cursor left one character 

M ove cursor to lower-1 eft corner 

Cursor left %i characters 

Turn soft labels off 

T urn soft labels on 

Start blinking 

Clear soft margins 

Start bold mode 

End all modes such as so, us, mb, md, and mr 

Start half bright mode 

Dark mode (Characters invisible) 

Set left soft margin 
Put terminal in meta mode 
Put terminal out of meta mode 
T urn on protected attribute 
Start reverse mode 
Set right soft margin 
C ursor right one character 
Carriage return command 
Padding character 
Turn printer off 

Program key %i to send string %2 asif typed by user 

Program key %i to execute string %2 in local mode 

Program soft label %i to show string %2 

T urn the printer on 

T urn the printer on for %i (<256) bytes 

Print screen contents on printer 

Program key %i to send string %2 to computer 

Reset string 1 to set terminal to sane modes 

Reset string 2 to set terminal to sane modes 

Reset string 3 to set terminal to sane modes 

D isable automatic margins 

Restore saved cursor position 

Reset string file name 
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RF 

Request for input from terminal 

RI 

Cursor right%i characters 

rp 

Repeat character %i for %2 times 

rP 

Padding after character sent in replacemode 

rs 

Reset string 

RX 

Turn off XON/XOFF flow control 

sa 

Set %i %2 %3 %4 %5 %e%7 %8 %9 attributes 

SA 

Enable automatic margins 

sc 

Save cursor position 

se 

End standout mode 

sf 

N ormal scroll oneline 

SF 

N ormal scroll %i lines 

so 

Start standout mode 

sr 

Reverse scroll 

SR 

Scroll back %i lines 

St 

Set tabulator stop in all rows at current column 

SX 

Turn on XON/XOFF flow control 

ta 

M ove to next hardware tab 

tc 

Read in terminal description from another entry 

te 

End program that uses cursor motion 

ti 

Begin program that uses cursor motion 

ts 

Move cursor to column %i of status line 

uc 

U nderline character under cursor and move cursor right 

ue 

End underlining 

up 

Cursor up oneline 

UP 

Cursor up %i lines 

us 

Start underlining 

vb 

V isible bell 

ve 

Normal cursor visible 

v i 

Cursor invisible 

vs 

Standout cursor 

wi 

Set window from line %i to %2 and column %3 to u 

XF 

XOFF character if not “S 

There are several ways of defining the control codes for string capabilities: 

N ormal characters except ■ 

, \, and % represent themselves. 

A “x means Ctrl+x. Ctrl-tA equalsl decimal. \* meansaspecial code, x can be one of the following characters: 

E 

Escape (27). 

n 

Linefeed (10). 

r 

Carriage return (13). 

t 

Tabulation (9). 
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b 

f 


r 

+ 

2 

d 

% 


Backspace (8). 

Form feed (12). 

Null character. A \xxx specifies the octal character xxx. 

I ncrements parameters by one. 

Single parameter capability. 

Add value of next character to this parameter and do binary output. 
Do ASCII output of this parameter with afield width of 2. 

Do ASCII output of this parameter with afield width of 3. 

Print a % 


If you use binary output, then you should avoid the null character because it terminates the string. You should reset tabulator 
expansion if a tabulator can be the binary output of a parameter. 

Warning: The preceding metacharacters for parameters may be wrong; they document M inixtermcap, which may not be 
compatible with Linux termcap. 

T he block graphic characters can be specified by three string capabilities: 
as Start the alternative charset, 

ae End it. 

ac Pairs of characters. The first character is the name of the block graphic symbol and 

the second character is its definition. 


Thefollowing names are available: 


i 


a 

f 

g 

h 

i 

k 

1 

m 

n 

o 

q 

s 

t 

u 

V 

w 

X 


Right arrow (>) 

Left arrow (<) 

D own arrow (v) 

Full square (#) 

Latern (#) 

Upper arrow (•) 

R horn bus (+) 

Chessboard (:) 

D egree( 1 ) 

Plus-minus(#) 

Square (#) 

Right bottom corner (+) 
Right upper corner (+) 
Left upper corner (+) 

Left bottom corner (+) 
Cross (+) 

Upper horizontal line(-) 
M iddlehorizontal line(-) 
Bottom horizontal line(_) 
Left tee (+) 

Right tee(+) 

Bottom tee(+) 

N ormal tee(+) 

Vertical line(_) 

Paragraph (???) 



T he values i n parentheses are suggested defaults that are used by curses if thecapabilities are missing. 
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SEE ALSO 

termcap(3), curses(3), terminfo(5) 


Linux 


ttytype 

ttytype— T erminal name and device list. 

DESCRIPTION 

The /etc/ttytype file associates termcap/terminfo terminal type names with tty lines. Each line consists of a terminal type, 
followed by whitespace, followed by a tty name (a device name without the /dev/ prefix). 

This association is used by the program tset(l) to set the environment variable term to the default terminal name for the 
user's current tty. 

This facility was designed for a traditional time-sharing environment featuring character-cell terminals hardwired to a U NIX 
minicomputer. It is little used on modern workstation and personal U N IXes. 

EXAMPLE 

A typical /etc/ttytype is 

con80x25 tty 1 
vt320 ttysB 

FILES 

/etc/ttytype Thetty definitionsfile 

SEE ALSO 

getty(l), terminfo(5), termcap(5) 

Linux, 24July 1993 


tzfile 

tzfile— T i me zone i nformati on. 

SYNOPSIS 

#include <tzfile.h> 


DESCRIPTION 


Thetimezoneinformation files used by tzset(3) beginwith bytes reserved for future use, followed by six four-byte values of 
type long, written in a "standard" byte order (the high-order byte of the value is written first). These values are, in order 


tzh_ttisgmtcnt 

tzh_ttisstdcnt 

tzh_leapcnt 

tzh_timecnt 

tzh_typecnt 

tzh charcnt 


The number of GMT/local indicators stored in thefile. 

Thenumberof standard/wall indicators stored inthefile. 

Thenumberof leap seconds for which data is stored in thefile. 

Thenumberof "transition times" for which data is stored in thefile. 

Thenumberof "local time types" for which data is stored in the file (must not be zero). 
Thenumberof characters of "timezoneabbreviation strings" stored in thefile 



Part V: File Formats 



Thepreceding header isfollowed by tzh_timecnt four-byte values of type long, sorted in ascending order. These values are 
written in "standard" byte order. Each is used as a transition time (as returned by time(2)) at which the rules for computing 
local time change. N ext come tzh_timecnt one-byte values of type unsigned chan; each one tells which of the different types 
of "local time" types descri bed in the file is associated with the same-indexed transition time. These values serve asindices 
into an array of ttinfo structures that appears next in the file; these structures are defined as follows: 

struct ttinfo { 
long tt_gmtoff; 
int tt_isdst; 
unsigned int tt_abbrind; 

}; 

Each structure is written as a four-byte value for tt_gmtoff of type long, in a standard byte order, followed by aone-byte 
value for tt_isdst and a one-byte value for tt_abbnind. In each structure, tt_gmtotf gives the number of seconds to be added 
to GMT, tt_isdst tells whether tm_isdst should beset by iocaitime(3) and tt_abbrind serves as an index into the array of 
timezoneabbreviation characters that follow the ttinfo structures in the file. 

Then there are tzh_ieapcnt pairsof four-byte values, written in standard byteorder; the first value of each pair gives thetime 
(as returned by time(2)) at which a leap second occurs; thesecond gives thetotal number of leap seconds to be applied after 
the given time. The pairs of values are sorted in ascending order by time 

Then there are tzh_ttisstdcnt standard/wall indicators, each stored as a one-byte value; they tell whether thetransition times 
associated with local time types were specified as standard time or wall clock time and are used when a time zone file is used 
in handling PO SIX-style time zone environment variables. 

Finally, there are tzh_ttisgmtcnt GMT/local indicators, each stored as a one-byte value; they tell whether thetransition times 
associated with local time types were specified asGM T or local time and are used when a time zone file is used in handling 
PO SIX-style time zone environment variables. 

Localtime uses the first standard-time ttinfo structure in the file (or simply the first ttinfo structure in the absence of a 
standard-time structure) if either tzh_timecnt is zero or the time argument is less than the first transition time recorded in the 
file. 

SEE ALSO 

newctime(3) 

utmp, wtmp 

utmp, wtmp — Login records. 

SYNOPSIS 

#include <utmp.h> 

DESCRIPTION 

The utmp file allows you to discover information about who is currently using the system. There may be more users currently 
using the system because not all programs use utmp logging. 

Warning: utmp must not be writable because many system programs depend on its integrity. You risk faked system log files 
and modificationsof system files if you leave utmp writable to any user. 

T he file is a sequence of entries with the followi ng structure declared in the include fi le 

#define UTJJNKNOWN 0 
#define RUNJ_VL 1 
#define BOOT_TIME 2 
#define NEW_TIME 3 
#define OLDTIME 4 
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#define INIT_PROCESS 5 
#define LOGIN_PROCESS 6 
#define USER_PROCESS 7 
#define DEAD_PROCESS 8 

#define UT_LINESIZE 12 
#define UT_NAMESIZE 8 
#define UT_HOSTSIZE 16 

struct utmp { 
short ut_type; 
pid_t ut_pid; 

char ut_line[UT_LINESIZE]; 
char ut_id[2]; 
time_t ut_time; 
char ut_user[UT_NAMESIZE]; 
char ut_host[UTHOSTSIZE]; 
long ut_addr; 

}; 

This structure gives the name of the special file associated with the user's terminal, the user's login name and thetimeof 
login in theform of time(2). String fields are terminated by \e if they are shorter than the size of the field. 

The first entries ever created result from init(8) processing inittab(5). Before an entry is processed, though, init(8) cleans 
up utmp by setting ut_type to dead process, clearing ut_user, ut_host and ut_time with null bytes for each record that ut_type 
is not deadprocess or run_lvl and where no process with PID ut_pid exists. If no empty record with the needed utpd can be 
found, init creates a new one. 11 sets ut_id from themittab, ut_pid and utpime to the current values, and utpype to 

INIT_PROCESS. 

getty(8) locates the entry by the PID, changes utpype to loginprocess, changes ut_time, setsut_iine and waits for 
connection to be established. iogin(8), after a user has been authenticated, changes ut_type to userprocess, changes utpime, 
and setsut_host and ut_addr. D epending on getty(8) and iogin(8), records may be located by utpine instead of the 
preferable utpid. 

When init(8) finds that a process has exited, it locates its utmp entry by ut_pid, setsut_type to deadprocess, and clears 
ut_user, ut_host, and ut_time with null bytes. 

xterm(l) and other terminal emulators directly create a userprocess record and generate the ut_id by using the last two 
letters of /dev/ttyp%c or by using p%d for /dev/pts/%d. 

If they find a dead_process for this ID, they recycle it; otherwise they create a new entry. If they can, they will mark it as 
dead process on exiting and itisadvised that they null ut_iine, ut_time, ut_user, and utpost aswell. 

xdm(8) should not create an utmp record because there is no assigned terminal. Letting it create one will result in trouble such 
as finger: cannot stat /dev/machine .dom. It should create wtmp entries, though, just like ttpd(8) does. 

teinetd ( 8) setsup a loginprocess entry and leaves the rest to iog±n(8) as usual. After theT el net session ends, teinetd(8) 
cleansup utmp in the described way. 

The wtmp file records all logins and logouts. Its format is exactly I ike utmp except that a null username indicates a logout on 
theassociated terminal. Furthermore, the terminal name- with username shutdown or reboot indicates a system shutdown or 
reboot and thepair of terminal names »•*/■}■ logs the old/new system time when date(l) changes it. wtmp ismaintained by 
login(l) and init(l) and some variation of getty(l). N either of these programs creates the file, so if it is removed, record¬ 
keeping is turned off. 

FILES 


/* type of login */ 

/* pid of process */ 

/* device name of tty - "/dev/" */ 
/* init id or abbrev. ttyname */ 

/* login time */ 

/* user name */ 

/* host name for remote login */ 

/* IP addr of remote host */ 


/var/run/utmp 

/var/log/wtmp 
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CONFORMING TO 

Linux utmp entries conform neither to v7/BSD nor to SYSV: T hey are a mix of the two. v7/BSD has fewer fields; most 
importantly, it lacks ut_type, which causes native v7/BSD-I ike programs to display (for example) dead or login entries. 
Further there is no configuration file that allocates slots to sessions. BSD does so because it lacks ut_±d fields. In Linux (as in 
SYSV), theut_id field of a record will never change once it is set, which reserves that slot without needing a configuration 
file. Clearing ut_id may result in race conditions leading to corrupted utmp entries and potential security holes. Clearing the 
previously mentioned fields by filling them with null bytes is not required by SYSV semantics, but it allows you to run many 
programs that assume BSD semantics and that do not modify utmp. Linux uses the BSD conventions for line contents. SYSV 
only uses the type field to mark them and logs informative messages such as new time in the line field. SYSV has one more 
field to log the exit status of dead processes, utjjnknown seems to be a Linux invention. There is no type accounting in Linux. 
SYSV has no ut_host or ut_addr fields. Uni ike various other systems, where utmp logging can be disabled by removing the 
file, utmp must always exist on Linux. If you want to disable who(l), then do not make utmp world readable. 

RESTRICTIONS 

The file format is machine dependent, so it is recommended that it be processed only on the machine architecture where it 
got created. 

SEE ALSO 

ac(l), date(l), last(l), login(l), who(l), getutent(3), init(8) 

20 July 1996 
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uuencode — Format of an encoded uuencodefile. 

DESCRIPTION 

Files output by uuencode(l) consist of a header line, followed by a number of body lines, and a trailer line T he uudecode(l) 
command will ignore any lines preceding the header or following the trailer. Lines preceding a header must not, of course, 
look like a header. 

The header line is distinguished by having the first six characters begin. The word begin is followed by a mode (in octal) and 
a string that names the remote file. A space separates the three items in the header line. 

The body consists of a number of lines, each at most 62 characters long (including the trailing newline). These consist of a 
character count, followed by encoded characters, followed by a newl ine. T he character count is a si ngle printi ng character 
and represents an integer, the number of bytes the rest of the line represents. Such integers are always in the range from 0 to 
63 and can be determined by subtracting the character space (octal 40) from the character. 

Groups of three bytes are stored in four characters, six bits per character. All are offset by a space to make the characters 
print. The last line may be shorter than the normal 45 bytes. If the size is not a multiple of three, this fact can be determined 
by the value of the count on the last line. Extra garbage will be included to make the character count a multiple of four. The 
body is terminated by a line with a count of zero. T his line consists of one ASC11 space. 

The trailer I ine consists of end on a line by itself. 

SEE ALSO 

uuencode(l), uudecode(l), uusend(l), uucp(l), mail(l) 

HISTORY 

The uuencode file format appeared in BSD 4.0. 
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XF86Config 

xF86Config— Configuration file for X Free86. 


DESCRIPTION 

XFree86 uses a configuration file called xFseconfig for its initial setup. This configuration file is searched for in the foil owing 
places: 

/etc/XF86Config 

<XRoot>/lib/X11/XF86Config.host name 
<X R o o t>/lib/X11/XF86Config 

<XRoot > refers to the root oftheXll install tree 

This file is composed of a number of sections Each section has the form: 

Section "Sect i on Name" 

Secti onEnt r y ... 

EndSection 


The section names are 
Files 

ServerFlags 

Keyboard 

Pointer 

Monitor 

Device 

Screen 


File pathnames 
Server flags 

Keyboard configuration 
Pointer configuration 
M onitor description 
Graphics device description 
Screen configuration 


The Files section isused to specify the default font path and the path to the RGB database. These paths can also beset from 
the command line (see xserver(l)). The entries avai lablefor this section are 

FontPath "path" Sets the search path for fonts. This path is a comma-separated list of directories that the X 

server searches for font databases. M ultiple FontPath entries may be specified, and they will 
be concatenated to bui Id up the fontpath used by the server. 

X11R6 allows the X server to request fonts from a font server. A font server is specified by 
placing a "<trans>/<hostname>:<port_number >" entry into the fontpath. For example the 
fontpath 

■/usr/X11R6/lib/X11/fonts/misc/,tcp/zok:7100" 

tel Is the X server to first try to locate the font in the local directory /usr/xi iRe/iib/xi i / 
fonts/misc. If that fails, then request the font from the font server running on machine zok 
listening for connections on TC P port number 7100. 

RGBPath "path" Sets the path name for the RG B color database. 

The ServerFlags section isused to specify some miscellaneous X server options. T he entries available for this section are 

NoTrapsignais ThispreventstheX server from trapping a range of unexpected fatal signalsand exiting 

cleanly. Instead, theX server will die and drop core where the fault occurred. The default 
behavior isfortheX server exit cleanly but still drop a core file. In general, you never want 
to usethisoption unless you are debugging an X server problem. 

Dontzap This disallows the use of the Ctrl+Alt-FB ackspace sequence. T his sequence allows you to 

terminate theX server. Setting Dontzap allows this key sequence to be passed to clients. 
Dontzoom This disallows the use of the Ctrl-hAlt+K eypad-P lus and Ctrl-tAlt+Keypad-M inus sequences. 

These sequences allow you to switch between video modes. Setting Dontzoom allows these 
key sequences to be passed to clients 
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The Keyboard section is used to specify the keyboard input device, parameters, and some default keyboard mapping options. 

T h e entri es avai I abl e fo r th i s secti o n are 

Protocol "kbd-protocoi" kbd-protocoi may be either standard or xqueue. xqueue is specified when using the event 

queue driver on SVR3 orSVR4. 

AutoRepeat delay rate C hanges the behavior of the autorepeat of the keyboard. This does not work on all 

platforms. 

serverNumLock ForcestheX server to handle the numlock key internally. T he X server sends a different set 

of keycodesfor thenumpad when the numlock key is active. This enables applications to 
make use of thenumpad. 

LeftAlt mapping RightAlt mapping AltGr mapping 
ScrollLock mapping RightCtl mapping 

Allows a default mapping to beset for the preceding keys (note that AitGr is a synonym for RightAlt). The values that may be 
specified for mappi ng are 

Meta 

Compose 

ModeShift 

ModeLock 

ScrollLock 

Control 


The default mapping when none of these options are specified is 
LeftAlt M eta 


RightAlt M eta 
ScrollLock Compose 
RightCtl Control 

XLeds led ... 
VTSysReq 

VTInit "command" 


M akesi ed available for clients instead of using the traditional function (Scroll Lock, Caps 
Lock, and N urn Lock), i ed isa list of numbers in the range 1 to 3. 

Enables the SYSV-styleVT switch sequence for non-SYSV systems that support VT 
switching. T his sequence is Alt-SysRq followed by a function key (Fn). T his prevents the X 
server trapping the keys used for the default VT switch sequence. 

Runscommand aftertheVT used by the server has been opened. The command string is 
passed to /bm/sh -c and is run with the real user's ID with stdin and stdout set to thevi. 

T he purpose of thisoption isto allow system-dependent VT initialization commands to be 
run. One example is a command to disable the two-key VT switching sequence that is the 
default on some systems. 


The Pointer section is used to specify the pointer device and parameters. The entries available for this section are 
Protocol "protocol - type " Specifies the pointer device protocol type. T he protocol types avai I able are 


BusMouse 

Logitech 

Microsoft 

MMSeries 

Mouseman 

MouseSystems 

PS/2 
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MMHitTab 


Xqueue 

OSMouse 


One should specify BusMouse for the Logitech bus mouse. Also, many newer Logitech serial mice use either the Microsoft or 
MouseMan protocol, xqueue should be specified here if it was used in the Keyboard section. OSMouse refers to the event-driver 
mouse interface available on SCO'sSVR3. This may optionally be followed by a number specifying the number of buttons 
the mouse has. 


Device "poi nter-dev" 

BaudRate rate 

Emulate3Buttons 

Emulate3Timeout timeout 

ChordMiddle 

SampleRate rate 

ClearDTR 


ClearRTS 


Specifies the device the server should open for pointer input (such as/dev/ttyoa 
or /dev/mouse). A device should not be specified when using the Xqueue or 
OSM ouse protocols 

Setsthebaud rate of the serial mouse to rate. Formicethat allow dynamicspeed 
adjustments (such as Logitech), the baud rate is changed in the mouse. 

Otherwise, the rate is simply set on the computer's side to allow mice with non¬ 
standard rates (the standard rate is 1200). 

Enables the emulation of the third mouse button formicethat only have two 
physical buttons. The third button is emulated by pressing both buttons 
simultaneously. 

Sets the time (in milliseconds) that the server waits before deciding if two 
buttons were pressed "simultaneously'' when three-button emulation isenabled. 
The default ti me-out is 50ms 

Handles mice that send left-might events when the middle button isused (such as 
some Logitech M ouseman mice). 

Sets the number of motion/button-events the mouse sends per second. This is 
currently only supported for some Logitech mice 
Thisoption clears theDTR lineon the serial portused by the mouse. This 
option isonly valid for a mouse using the Mousesystems protocol. Some dual¬ 
protocol mice require DTR to be cleared to operate in Mousesystems mode. N ote 
in versions of XFree86 prior to 2.1, thisoption also cleared the RTS line. A 
separate ciearRTs option has since been added for mice that require this. 
Thisoption clears the RTS lineon the serial port used by the mouse. Thisoption 
isonly valid for a mouse using the Mousesystems protocol. Some dual-protocol 
mice require both DTR and RTSto be cleared to operatein Mousesystems mode. 
Both the ciearDTR and ciearRTs options should beused for such mice 


The Monitor sections are used to definethespecifications of a monitor and a list of video modes suitable for use with a 
monitor. M ore than one Monitor section may be present in an xF86Contig file. The entries avai lablefor this section are 


Identifier "ID string" 

VendorName "vendor" 
ModelName "model " 
HorizSync horizsync-range 


This specifies a string by which the monitor can be referred to in a later screen 
section. Each Monitor section should haveauniquelD string. 

This optional entry specifies the monitor's manufacturer. 

This optional entry specifies the monitor's model. 

Gives the ranges of horizontal sync frequencies supported by the monitor, 
hori zsync-range may be a comma-separated list of either discrete values or ranges 
ofvalues. A rangeof values istwo values separated byadash. Bydefault, the 
values are in units of kH z. They may be specified in M H zor Hz if M H zor H z is 
added to the end of the line. The data given here is used by theX server to 
determine if video modes are within the specifications of the monitor. This 
information should be available in the monitor's handbook. 
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VertRefresh vert refre sh -range 


Gamma gamma - vaI ues 


Mode "name" 


DotClock clock 


Gives the ranges of vertical refresh frequencies supported by the monitor. 
»ert refresh-range may be a comma-separated list of either discrete values 
or ranges of values. A range of values istwo values separated by a dash. By 
default, the values are in units of Hz. They may be specified in M Hz or 
kHz if M Hz or kHz is added to the end of the line. The data given here is 
used by theX server to determine if video modes are within the 
specifications of the monitor. T his information should be available in the 
monitor's handbook. 

T his is an optional entry that can be used to specify the gamma 
correction for the monitor. It may be specified as either a single value or 
as three separate RGB values. Not all X servers are capable of using this 
information. 

Indicates the start of a multi-line video mode description. The mode 
description is termi nated with an End-M odeline. The mode description 
consists of the following entries: 

T he dot clock rate to be used for the mode. 


HTimings hdi sp h s y n c s t art hsyncend htotai Specifies the horizontal timi ngs for the mode. 

vTimings v d i s p vsyncst art vsyncend vtotai Specifies the vertical timingsfor the mode. 

Flags "flag" ... Specifies an optional set of mode flags, interlace indicatesthat the mode 

is interlaced. Doublescan indicates a mode where each scanline is doubled. 
+HSync and -HSync can be used to select the polarity of the H Sync signal. 
+vsync and -vsync can beused to select thepolarity of theVSyncsignal, 
composite can beused to specify composite sync on hardware where thisis 
supported. Additionally, on some hardware, +csync and -csync may be 
used to select the composite sync polarity. 

Modeiine "name" mode-descri pti on A single line format for specifyi ng video modes. T hemode- des c r i pt i on is 

in four sections, the first three of which are mandatory. The first isthe 
pixel clock. This is a single number specifying the pixel clock rate for the 
mode. The second section is a list of four numbers specifying the 
horizontal timings. These numbers are the hdisp, hsyncstart, hsyncend, 
htotai. T hethird section isa list of four numbers specifying the vertical 
timings. T hese numbers are vdisp, vsyncstart, vsyncend, vtotai. T he final 
section isa list of flags specifying other characteristics of the mode, 
interlace indicates that the mode is interlaced. Doublescan indicatesa 
mode where each scanline is doubled. +HSync and -HSync can beused to 
select the polarity of theHSync signal. +vsync and-vsync can be used to 
select the polarity of thevsync signal, composite can beused to specify 
composite sync on hardware where this issupported. Additionally, on 
some hardware, +csync and -csync may be used to select the composite 
sync polarity. 


The Device sections are used to define a graphics da/ice (video board). M ore than one Device section may be present in an 
xF86Contig file. T he entries avai lable for this section are 


Identifier "ID string" 

VendorName "vendor" 
BoardName "model " 
Chipset "chi pset-type" 


This specifies a string by which the graphics da/ice can be referred to in a 
later screen section. Each Device section should have a unique ID string. 
This optional entry specifies the graphics da/ice's manufacturer. 

This optional entry specifies the name of the graphics da/ice. 

This optional entry specifi es the chi pset used on the graphics board. I n 
most cases, this entry is not required because theX servers will probe the 
hardware to determine the chi pset type. 



XF86Config 



Ramdac "r amdac - 1 y pe " 


DacSpeed speed 


Clocks clock 


ClockChip "cl ockchi p-type 


ClockProg command [textclock] 


Option optionstring 


VideoRam mem 


BIOSBase baseaddress 


Thisoptional entry specifies the type of RAM DAC used on thegraphics board. 
This is only used by a few of the X servers, and in most cases, it is not required 
because the X servers will probe the hardware to determine the RAM DAC type 
where possible. 

Thisoptional entry specifies theRAM DAC speed rating (which is usually 
printed on theRAM DAC chip). Thespeed isin M Hz. This is only used bya 
few of theX servers and only needs to be specified when thespeed rating of the 
RAM DAC is different from the default built in to theX server. 

Specifies the dotclocks that are on your graphics board. The clocks are in MHz 
and may be specified as a floating-point number. The value is stored internally to 
the nearest kHz. The ordering of the clocks is important. It must match the 
order in which they are selected on the graphics board. M ultiple clocks lines may 
be specified. For boards with programmableclock chips, theciockchip entry 
should be used instead of this A clocks entry is not mandatory for boards with 
non-programmable clock chips but is highly recommended because it prevents 
the clock probing phase during server startup. This clock probing phase can 
cause problems for some monitors 

Thisoptional entry is used to specify the clock chip type on graphics boards that 
have a programmableclock generator. OnlyafewX servers support program¬ 
mableclock chips. For details seetheappropriateX server manual page. 
Thisoptional entry runscommand to settheclock on the graphics board instead of 
using the internal code. The command string must consist of the full pathname 
(and no flags). W hen usi ng this option, a clocks entry is required to specify 
which clock values are to be made avail able to the server (up to 128 clocks may 
be specified). The optional text ci ock value is to tell the server that command must 
be run to restore the text-mode clock at server exit (or when VT switching), 
text ci ock must match one of the values in the clocks entry. This parameter is 
required when theclock used fortext mode is a programmableclock. 

The command is run with the real user's ID with stdin and stdout set to the 
graphics console device. T wo arguments are passed to the command. The first is 
theclock frequency in M Hz as a floating-point number andthesecond isthe 
index of theclock in theciocks entry. The command should return an exit status 
of 0 when successful and something in the range 1-254 otherwise. 

The command is run when the initial graphics mode isset and when changing 
screen resolution with the hotkey sequences. If the program fails at initialization, 
the server exits If it fails during a mode switch, the mode switch is aborted but 
the server keeps running. It is assumed that if the command fails, theclock has 
not been changed. 

Thisoptional entry allows the user to select certain options provided by the 
drivers. M ultiple option entriesmay be given. The supported values for 
opt i onst r i ng are given in the appropriate X server manual pages. 

Thisoptional entry specifies theamount of video RAM that is installed on the 
graphics board. This is measured in kilobytes. In most cases, thisisnot required 
because theX server probes the graphics board to determine this quantity. 

This optional entry specifi es the base address of the video B10 S for the V G A 
board. This address is usually OxCOOOO, which is the default theX servers use. 
Somesystems, particularly those with on-board VGA hardware, havetheBIOS 
located at an alternate address, usually OxEOOOO. If your video BIOS is at an 
address other than OxCOOOO, you must specify the base address in thexF86Config 
file. N otethat someX servers don't access the BIOS at all and those that do only 
use the B10 S when searching for information during the hardware probe phase. 
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MemBase baseaddress 

IOBase baseaddress 

DACBase baseaddress 

POSBase baseaddress 

COPBase baseaddress 

VGABase baseaddress 

Instance number 

Speedup sel ecti on 

S3MNAdj ust MN 
S3MClk clock 

S3RefClock clock 


This optional entry specifies the memory base address of a graphics board's li near 
framebuffer. This entry is only used by a few X servers, and the interpretation of 
this base address may be different for different X servers. Refer to the appropriate 
X server manual page for details. 

This optional entry specifies the 10 baseaddress. This entry is only used for a 
fewX servers. Refer to theappropriateX server manual page for details 
Thisoptional entry specifies the D AC baseaddress. This entry is only used fora 
fewX servers. Refer to theappropriateX server manual page for details 
Thisoptional entry specifies the POS baseaddress. This entry is only used for a 
fewX servers. Refer to theappropriateX servermanual page for details 
Thisoptional entry specifies the coprocessor baseaddress. This entry isonly used 
forafewX servers. Refer to theappropriateX servermanual page for details 
Thisoptional entry specifies theVGA memory baseaddress. This entry isonly 
used for a few X servers. Refer to theappropriateX server manual page for 
details. 

Thisoptional entry specifies the instance (which indicates if the chip is 
integrated on the motherboard or on an expansion card). This entry isonly used 
forafewX servers. Refer to theappropriateX servermanual page for details 
Thisoptional entry specifies the selection of speedupsto be enabled. This entry 
is only used forafewX servers. Refer to theappropriateX server manual page for 
details. 

Thisoptional entry is specific to the S3 X server. For details refer to the 
xf86_s3(i ) manual page. 

Thisoptional entry is specific to the S3 X server. For details refer to the 
xf86_s3(i ) manual page. 

Thisoptional entry is specific to the S3 X server. For details refer to the 
xf86_S3 ( i ) manual page. 


The screen sections are used to specify which graphics boards and monitors are used with a particular X server and the 
configuration in which they are to be used. T he entries availablefor this section are 

Driver d r i v e r - n a me Each screen section must begi n with a Driver entry, and the dr i v e r - n a me given in 

each screen section must be unique. The dr i ver • name determines which X server 

(or driver type within an X server when an X server supports more than one 

head) reads and uses a particular screen section. The driver names available are 

Accel 

Mono 

SVGA 

VGA2 


Device devi ce-i d 
Monitor moni t or - i d 
ScreenNo scr num 


VGA16 

Accel isused by all the accelerated X servers (seexF86_Accei(l)). Mono isused by 
the non-VGA mono drivers in the 2-bit and 4-bit X servers (see xF86_Mono(l) and 
xf86_vgai 6(1)). vga 2 and vgai6 areused by theVGA drivers in the 2-bit and 4-bit 
X servers, svga is used by the xf86_svga X server. 

Specifies which graphics devicedescription isto beused. 

Specifies which monitor description isto beused. 

Thisoptional entry overrides the default screen numberingin a multi-headed 
confi guration. T he default numberi ng is determined by the orderi ng of the 
screen sections in thexF86Config file. T o override this, all relevant screen 
sections must have this entry specified. 
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BlankTime t i me 


SuspendTime t i me 


Off Time t i me 


Subsection Display 


Depth bpp 


Weight RGB 


Virtual xdi m ydi m 


Viewport xO yO 


Modes mode name 


InvertVCLK modename 011 


Sets the inactivity time-out for the blanking phase of the screensaver, ti me isin 
minutes, and the default is 10 . This is equivalent to theX server's -s flag, and the 
value can be changed at runtime with xset(l). 

Sets the inactivity time-out for the "suspend" phase of the screensaver, ti me isin 
minutes, the default is 15, and it can be changed at runtime with xvidtune(l). This 
isonly suitablefor VESA DPM S compatiblemonitorsand is only supported 
currently by someX servers. The "power_saver" option must beset for this to be 
enabled. 

Sets the inactivity time-out for the "off" phase of the screensaver, ti me isin minutes, 
the default is 30 , and it can be changed at runtime with xvidtune(l). This is only 
suitable for VESA D PM S compatiblemonitorsand isonly supported currently by 
someX servers. The"power_saver" option must be set for this to be enabled. 

This entry isa subsection that is used to specify some display specific parameters. 
This subsection isterminated by an Endsubsection entry. For someX servers and 
drivers (those requiring a list of video modes), this subsection ismandatory. ForX 
servers that support multiple display depths, more than one Display subsec-tion can 
be present. W hen multiple Display subsections are present, each must have a unique 
Depth entry. T he entries available for the Display subsection are 
This entry ismandatory when more than oneDispiay subsection ispresent in a 
screen section. W hen only oneDispiay subsection ispresent, it specifies the default 
depth where theX server will run. W hen more than oneDispiay subsection is 
present, the depth determines which gets used by theX server. The subsection used 
isthe one matching thedepth at which theX server is run. Not all X serversfor 
drivers) support more than onedepth. Permitted values for bpp ares, 15,1 6 , 24 , and 
32 . N ot all X servers (or drivers) support all these values, bpp values of 24 and 32 are 
treated equivalently by thoseX servers that support them. 

This optional entry specifies the relative RGB weighting to be used for an X server 
running at 16bpp. This may also be specified from the command line (see 
xFree86(l)). Values supported by most 16bppX servers are 555 and 565. For further 
details, refer to theappropriateX server manual page. 

Thisoptional entry specifies thevirtual screen resolution to beused. xdi m must bea 
multiple of either 8 or 16 for most color X servers and a multiple of 32 for the 
monochromeX server. Thegiven value is rounded down if this is not the case. For 
mostX servers, video modes that are too large for the specified virtual size are 
rejected. If thisentry is not present, thevirtual screen resolution isset to accommo¬ 
date all thevalid video modes given in theModes entry. SomeX servers do not 
support thisentry. Refer to theappropriateX server manual pages for detai Is. 

This optional entry sets the upper-left corner of the initial display. T his is only 
relevant when thevirtual screen resolution is different from the resolution of the 
initial video mode. If thisentry is not given, then the initial display is centered in the 
virtual display area. 

Thisentry is mandatory for mostX servers, and it specifies the list of video modes to 
use. The video mode names must correspond to those specified in the appropriate 
Monitor section. MostX servers delete modes from this list that don't satisfy various 
requirements. The first valid mode in this list is the default display mode for startup. 
The list of valid modes is converted internally into a circular list. It is possible to 
switch to the next mode with Ctrl+Alt-fKeypad Plus and to the previous mode with 
Ctrl-fAlt+Keypad M inus. 

Thisoptional entry is specific to the S3 server only. It can beused to change the 
default VC LK inverty non-invert state for individual modes. If "modename 11 is 11 ", the 
setting applies to all modes unless overridden by later entries. 
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EarlySC mode name 0|1 


BlankDelay modename valuel va I ue2 


Visual vi sual • name 


Option optionstring 

Black red green blue 
White red green blue 


This optional entry isspecificto the S3 server only. It can beusedto change the 
default Eaniysc setting for individual modes. Thissetting can affect screen wrapping. 
If "modename " is the setting applies to all modes unless overridden by later entries. 
Thisoptional entry is specific to the S3 server only. It can beusedto change the 
default blank delay settings for individual modes. This can affect screen wrapping, 
vaiuei and vai ue 2 must be integers in the range 0-7. If "modename" is 11 ", the setting 
applies to all modes unless overridden by later entries. 

Thisoptional entry sets the default root visual type. This can also be specified from 
the command line (see xserver(l)). T he visual types avai lable for 8bpp X servers are 
(default is Pseudocolor): 

StaticGray 

Grayscale 

StaticColor 

Pseudocolor 

TrueColor 

DirectColor 

T he visual type available for the 16bpp and 32bpp X servers is TrueColor. 

T he visual type available for the lbppX server is StaticGray. 

The visual types avai I able for the 4bpp X server are (default is Pseudocolor): 

StaticGray 

Grayscale 

StaticColor 

Pseudocolor 

Thisoptional entry allows the user to select certain options provided by the drivers. 
M ultiple option entries can be given. The supported values foropti on-stri ng are 
given in theappropriateX server manual pages. 

This optional entry allows the "black'' color to be specified. T his is only supported 
with theVGA2 driver in thexF86_Mono server (for details, seexF86_Mono(l)). 

This optional entry allows the "white” color to be specified. T his isonly supported 
with theVGA2 driver in thexF86_Mono server (for details, seexF86_Mono(l)). 


For an exampleof an xF86Config file, seethefileinstalled as<xRoot>/iib/xii/xF86Config.eg. 


FILES 

/etc/XF86Config 

<XRoot>/lib/X11/XF86Config. hostname <XRoot>/lib/X11/XF86Config 
N otethat <xRoot> refers to the root of theX11 install tree. 


SEE ALSO 

X(l), Xserver(l), XFree86(l), XF86_SVGA(1), XF86_VGA16(1), XF86_Mono(l), XF86_S3(1), XF86 8514(1), XF86_Mach8(l), 
XF86Jlach32(l), XF86_P9000(1), XF86_AGX(1), XF86_W32<1) 

AUTHORS 

Refer to thexFree86(l) manual page. 
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intro 

intro— Introduction to games. 

DESCRIPTION 

This chapter describes all the games and funny little programs available on the system. 

AUTHORS 

Look at the header of the manual page for the authors and copyright conditions. Note that these can be different from page 
to page! 

Linux, 24July 1993 


banner 

banner— Print large banner on printer. 

SYNOPSIS 

/usr/games/banner [ -wn ] message ... 

DESCRIPTION 

banner printsa large, high-quality banner on thestandard output. If the message is omitted, it promptsfor and reads oneline 
of its standard input. If -w is given, the output is scrunched down from a width of 132 to n, suitable for a narrow terminal. If 
n is omitted, it defaults to 80 . 

The output should be printed on a hard-copy device, up to 132 columns wide, with no breaks between the pages. The 
volume is great enough that you might want a printer or a fast hard-copy terminal, but if you are patient, adecwriter or 
other 300 baud terminal will do. 

BUGS 

Several ASCII characters are not defined, notably <, , and \ Also, the characters ■, ■, and & are funny¬ 

looking (but in a useful way). 

The -w option is implemented by skipping some rows and columns. The smaller it gets, the grainier the output. Sometimes it 
runs letters together. 

AUTHOR 

M ark H orton 

6 Junel993 


ddate 

delate— Converts boring normal datestofun Discordian dates. 

SYNOPSIS 


ddate 



ddate 


1211 


DESCRIPTION 

ddate prints the date in D iscordian date format. 

AUTHOR 

D ruel the Chaotic, a.k.a. Jeremy Johnson (mpython9gnu.ai.mit.edu). M odificationsfor U N IX by LeeH arvey Oswald Smith, 
K.S.C. Five tons of flax. 

55 Confuaon 3160 
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intro 

intro— Introduction to miscellany section. 

DESCRIPTION 

This chapter describes miscellaneous things such asnroff macro packages, tables, C header files, the file hierarchy, general 
concepts, and other things that don't fit anywhere else. 

AUTHORS 

Look at the header of the manual page for the authors and copyright conditions. Note that these can be different from page 
to page! 

Linux, 23 April 1993 


ascii 

ascii— TheASCII character set encoded in octal, decimal, and hexadecimal 

DESCRIPTION 

T he following table contai nsthe 128 ASCII characters. 

C program '\X' escapes are noted. 


Oct 

Dec 

Hex 

Char 

Oct 

Dec 

Hex 

Char 

000 

0 

00 

N U L '\0' 

C3Hf 

64 

40 

@ 

001 

1 

01 

SOH 



41 

A 

002 

2 

02 

STX 


66 

42 

B 

003 

3 

03 

ETX 

m IN 

67 


C 

004 

4 

04 

EOT 



44 

D 

005 

5 

05 

ENQ 

m 

69 

45 

E 

006 

6 

06 

ACK 

-1 


46 

F 

007 

7 

07 

BEL V 

107 

71 

47 

G 

010 

8 

08 

BS '\b' 

110 

72 

48 

H 

Oil 

9 

09 

HT '\t' 

111 

73 

49 

1 

012 

10 

0A 

LF '\n' 

112 

74 

4A 

J 

013 

11 

0B 

VT V 


75 

4B 

K 

014 

12 

OC 

FF '\f' 

114 

76 


L 

015 

13 

OD 

C R V 

115 

77 

4D 

M 

016 

14 

OE 

SO 

116 

78 

4E 

N 

017 

15 

OF 

SI 

117 

79 

4F 

0 

020 

16 

10 

DLE 

120 


50 

P 

021 

17 

11 

DC1 

121 

81 

51 

0 

022 

18 

12 

DC2 


82 

52 

R 

023 

19 

13 

DC3 


83 

53 

S 

024 

20 

14 

DC4 

124 

84 

54 

T 

025 

21 

15 

NAK 

125 

85 

55 

U 

026 

22 

16 

SYN 

126 

86 

56 

V 
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Oct 

Dec 

Hex 

Char 

Oct 

Dec 

Hex 

Char 

027 

23 

17 

ETB 

127 

87 

57 

W 

030 

24 

18 

CAN 

130 

88 

58 

X 

031 

25 

19 

EM 

131 

89 

59 

Y 

032 

26 

1A 

SUB 

132 

90 

5A 

Z 

033 

27 

IB 

ESC 

133 

91 

5B 

[ 

034 

28 

1C 

FS 

134 

92 

5C 

Y\V 

035 

29 

ID 

GS 

135 

93 

5D 

] 

036 

30 

IE 

RS 

136 

94 

5E 

a 

037 

31 

IF 

US 

137 

95 

5F 


040 

32 

20 

SPACE 

140 

96 

60 

< 

041 

33 

21 

! 

141 

97 

61 

a 

042 

34 

22 

" 

142 

98 

62 

b 

043 

35 

23 

# 

143 

99 

63 

c 

044 

36 

24 

$ 

144 

100 

64 

d 

045 

37 

25 

% 

145 

101 

65 

e 

046 

38 

26 

& 

146 

102 

66 

f 

047 

39 

27 

• 

147 

103 

67 

g 

050 

40 

28 

( 

150 

104 

68 

h 

051 

41 

29 

) 

151 

105 

69 

i 

052 

42 

2A 

* 

152 

106 

6 A 

j 

053 

43 

2B 

+ 

153 

107 

6 B 

k 

054 

44 

2C 

, 

154 

108 

6 C 

1 

055 

45 

2D 

- 

155 

109 

6 D 

m 

056 

46 

2E 


156 

110 

6 E 

n 

057 

47 

2F 

/ 

157 

111 

6 F 

0 

060 

48 

30 

0 

160 

112 

70 

P 

061 

49 

31 

1 

161 

113 

71 

q 

062 

50 

32 

2 

162 

114 

72 

r 

063 

51 

33 

3 

163 

115 

73 

s 

064 

52 

34 

4 

164 

116 

74 

t 

065 

53 

35 

5 

165 

117 

75 

u 

066 

54 

36 

6 

166 

118 

76 

V 

067 

55 

37 

7 

167 

119 

77 

w 

070 

56 

38 

8 

170 

120 

78 

X 

071 

57 

39 

9 

171 

121 

79 

y 

072 

58 

3A 


172 

122 

7A 

z 

073 

59 

3B 

) 

173 

123 

7B 

{ 

074 

60 

3C 

< 

174 

124 

1C 

1 

075 

61 

3D 

= 

175 

125 

ID 

} 

076 

62 

3E 

> 

176 

126 

IE 

~ 

077 

63 

3F 

? 

177 

127 

7F 

DEL 
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HISTORY 

An ascii manual page appeared in version 7 AT&T UNIX. 

SEE ALSO 

iso_8859_1 (7) 

Linux 


bootparam 

bootparam— Introduction to boot-time parameters of the Linux kernel. 

DESCRIPTION 

TheLinux kernel accepts certain command-line options or boot-time parameters at the moment it is started. In general, this 
is used to supply the kernel with information about hardware parameters that the kernel would not be able to determine on 
its own, or to avoid or override thevalues that the kernel would otherwise detect. 

When the kernel is booted directly by the BIOS (say, from a floppy to which you copied a kernel using cp zimage / dev/f do), 
you have no opportunity to specify any parameters. T o take advantage of this possibility, you have to use software that is able 
to pass parameters, such as LILO or loadlin. For a few parameters, one can also modify the kernel image itself, using rdev; see 
rdev(8) for further details 

The LILO program (Linux LOader) written by Werner Almesberger is the most commonly used. It has the ability to boot 
various kernels and stores the configuration information in aplain text file. (See iiio(8) and liio.cont (5).) LILO can boot 
DOS, OS/2, Linux, FreeBSD, and so on and is quite flexible. 

The other commonly used Linux loader is loadlin, which is a DOS program that has the capability to launch a Linux kernel 
from theDOS prompt (with boot args) assuming that certain resources are avail able. This is good for people who want to 
launch Linux from DOS. 

It is also very useful if you have certain hardware that relies on the supplied DOS driver to put the hardware into a known 
state. A common example is SoundBlaster-compatible sound cards that requi re the DOS driver to twiddle a few mystical 
registers to put the card into aSB-compatiblemode. Booting DOS with the supplied driver and then loading Linux from the 
DOS prompt with loadlin avoids the reset of the card that happens if one reboots instead. 

THE ARGUMENT LIST 

M ost of the boot args take the form of 
n a me [ =v a I u e _ 1 ] [, v a I ue_2]...[,val u e _ 11 ] 

name is a unique keyword that is used to identify what part of the kernel the associated values (if any) are to be given to. 

M ultiple boot args are just a space-separated list of the preceding format. N ote the limit of 11 is real because the present code 
handles only 11 comma-separated parameters per keyword. (FI owever, you can reuse the same keyword with up to an 
additional 11 parameters in unusually complicated situations, assuming the setup function supports it.) 

M ost of the sorting occurs in linux/init/main.c. First, the kernel checks to see if the argument is any of the special 
arguments root=, ro, rw, or debug. The meaning of these special arguments is described later in the document. 

Then, it walks a list of setup functions (contained in thebootsetups array) to see if the specified argument string (such as too) 
is associated with a setup function (too_setupo) for a particular device or part of the kernel. If you passed the kernel the line 
f 00 = 3 ,4, 5 ,6, then the kernel searches thebootsetups array to see if too is registered. If it is, it cal Is the setup function 
associated with too (foo_setupo) and hands it the arguments 3,4,5, and 6 as given on the kernel command line. 

Anything of theform foo=bar that is not accepted as a setup function as described is then interpreted as an environment 
variableto beset. A (useless?) example isto useTERM=vti0o as a boot argument. 
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Any remaining arguments that were not picked up by the kernel and were not interpreted as environment variables are then 
passed onto process one which is usually the init program. The most common argument that is passed to theinit process is 
theword single, which instructs init to boot the computer in singleuser mode and not launch all theusual daemons Check 
the manual page for the version of init installed on your system to see what argumentsit accepts. 

GENERAL NON-DEVICE-SPECIFIC BOOTARGS 

no387 

Somei387 coprocessor chips have bugs that show up when used in 32-bit protected mode. 

For example, some of the early U LSI-387 chips cause solid lockups while performing floating-point calculations Using the 
1 no387 1 bootarg causes Linux to i gnore the maths coprocessor a/en if you have one. Of course, you must then have your 
kernel compiled with math emulation support! 

no-hlt 

Some of the early i486D X-100 chips have a problem with the hit instruction in that they can't reliably return to operating 
mode after this instruction is used. Using the no-hit 1 instruction tel Is Linux to just run an infinite loop when there is 
nothing else to do and to not halt the CPU. This allows people with these broken chips to use Linux. 

root=... 

This argument tel Is the kernel what device is to be used as the root filesystem while booting. The default of this setting is 
determined at compile time and usually is the value of the root device of the system that the kernel was built on. To override 
this value and select the second floppy drive as the root device, one uses ■ root=/dev/fdi 1 . (The root device can also beset 
using rdev(8).) 

The root device can be specified symbolically or numerically. A symbolic specification has the form /dev/xxYN, where xx 
designates the device type (hd for ST-506-compatible hard disk with y in a-h; sd for SC SI-compatible disk with y in a-e; xd 
for XT-compatible disk with y either a or b; fd for floppy disk with y the floppy drive number— tda istheDOS A: drive and 
tdi is B:), y isthe driver letter or number, andN isthe number of the partition on this device (absent in the case of floppies). 

N otethat this has nothing to do with the designation of these devices on your filesystem. The /dev/ part is purely conven¬ 
tional. 

T he more awkward and less portable numeric specification of the previous possible root devices in major/minor format is 
also accepted. (For example, /dev/sda3 is major 8, minor 3, so you can use root=0x803 as an alternative.) 

r o and r w 

Thero option tel Is the kernel to mount the root filesystem as readonly so that filesystem consistency check programs (tsck) 
can do their work on a quiescent filesystem. N o processes can write to files on the filesystem in question until it is re¬ 
mounted as read/write capable, such as by mount -w -n -o remount /. (See also mount(8).) 

The rw option tells the kernel to mount the root filesystem read/write. Thisisthe default. 

The choice between read-only and read/write can also beset usingrdev(8). 

debug 

Kernel messages are handed off to the kernel log daemon kiogd so that they can be logged to disk. M essageswith a priority 
above consoie_iogievei are also printed on theconsole. (For these levels, see<iinux/kernei.h>.) By default, this variable is set 
to log anything more important than debug messages. This boot argument causes the kernel to also print the messages of 
debug priority. The console log level can also beset at runtime viaan option to kiogd. Seekiogd(8). 

r e s e r v e =... 

This is used to protect I/O port regions from probes. The form of the command is 

reserved obase,extent [,iobase,extent ]... 
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In some machines, it might be necessary to prevent device drivers from checki ng for devices (auto-probing) in a specific 
region. This may be because of hardware that reacts badly to the probing, hardware that would be mistakenly identified, or 
hardware you don't want the kernel to initialize. 

The reserve boot-time argument specifies an I/O port region that shouldn't be probed. A device driver does not probe a 
reserved region unless another boot argument explicitly specifies that it do so. 

For example, the boot line 

reserve=0x300,32 blah=0x300 

keeps all device drivers except the driver for biah from probi ng 0x300-0x31f. 

r amdi s k=.., 

This option is obsolete si nee Linux 1.3.48 or so. It specifies the size in kilobytes of the optional RAM disk device. For 
example, if one wants to have a root filesystem on a 1.44M B floppy loaded into the RAM disk device they use 

ramdisk=1440 

This option is set at compile time (default is no RAM disk), and can be modified using rdev(8). 

mem=. .. 

The BIOS call defined in the PC specification that returns the amount of installed memory was only designed to be able to 
report up to 64M B. Linux uses this BIOS call at boot to determine how much memory is installed. If you have more than 
64M B of RAM installed, you can use this boot argto tell Linux how much memory you have. The value is in decimal or 
hexadecimal (prefix Ox), and the suffixes k (times 1024) or m (times 1048576) can be used. The following quote from Linus 
describes the use of themem= parameter: 

"The kernel will accept any mem=*x parameter you give it, and if it turns out that you lied to it, it will crash horribly sooner or 
later. T he parameter indicates the highest addressable RAM address, so mem= 0 xi 000000 ' meansyou havel6MB of memory, 
for example. Fora96M B machinethiswould be 1 ^= 0 x 6000000 . 

NOTE: Some machines might use the top of memory for BIOS caching or whatever, so you might not actually have up to 
the full 96M B addressable. The reverse is also true: Some chipsets will map the physical memory that is covered by the BIOS 
area into the area just past the top of memory, so thetop-of-mem might actually be96M B + 384KB, for example. If you tell 
Linux that it has more memory than it actually does have, bad things will happen: maybe not at once, but surely eventually.'' 

reboot =war m 

Since 2.0.22, a reboot is by default a cold reboot. This command-line option changes back to the old default, a warm reboot. 

B00TARGUMENTS FOR SCSI DEVICES 

General notation for this section: 

iobase— the first I/O port that the SC SI host occupies. These are specified in hexadecimal notation and usually lie in the 
rangefrom 0x200 to 0x3ff. 

irq— the hardware interrupt that the card is configured to use. Valid values are dependent on the card in question but are 
usually 5 , 7 , 9 , 10 , 11 , 12 , and 15 . The other values are usually used for common peripherals such as ID E hard disks, floppies, 
serial ports, and so on. 

scsi-id — the ID that the host adapter uses to identify itself on the SC SI bus. Only some host adapters allow you to change 
thisvalue because most have it permanently specified internally. The usual default value is 7, but the Seagate and Future 
Domain TMC-950 boards use 6. 

parity— whether the SC SI host adapter expects the attached devices to supply a parity value with all information exchanges. 
Specifying a 1 indicates parity checking is enabled, and a@ disables parity checking. Again, not all adapters support selection 
of parity behavior as a boot argument. 
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max_scsi_luns=... 

A SCSI device can have a number of subdevices contained within itself. The most common example is one of the new SCSI 
CD-ROM s that handle more than one disk at a time. Each CD is addressed as a Logical Unit N umber (LU N) of that 
particular device M ost devices, such as hard disks and tape drives, are only one device and are assigned to LU N 0 . 

Some poorly designed SC SI da/ices cannot handle being probed for LU N s not equal to 0 . T herefore, if the compile-ti me flag 
CONFIG scsi multi lun is not set, newer kernels by default only probe LU N 0. 

T 0 specify the number of probed LU N sat boot, one enters max scsi iuns=n as a boot arg, where n is a number between 1 
and 8. To avoid problems as described, one uses n=i to avoid upsetting such broken devices. 

SCSI TAPE CON FIGURATION 

Some boot-time configuration of theSCSI tapedriver can be achieved with the following: 

st=b u f _ s i ze[,write_threshold[ J max_bufs]] 

Thefirsttwo numbers are specified in units of kilobytes. T he default but _ s i z e is 32K B, and the maximum size that can be 
specified is a ridiculous 16384KB. The wr i te.t hr es hoi d is the value at which the buffer is committed to tape with a default 
value of 30KB. The maximum number of buffers varies with the number of drives detected and has a default of two. A 
sample usage is 

st=32,30,2 

Full details can be found in the readme, st file that is in the scsi directory of the kernel source tree. 

ADAPTEC AHA151X, AHA152X, AIC6260, AIC6360, SB16-SCSI CONFIGURATION 

The aha numbers refer to cards and the aic numbers refer to the actual SCSI chip on these types of cards, including the 
SoundBlaster-16 SCSI. 

The probe code for these SC SI hosts looks for an installed BIOS, and if none is present, theprobewill notfind your card. 

T hen you must use a boot arg of the form: 

aha152x=i obase [,i rq [,scsi - i d[, reconnect [,parity]]]] 

If the driver was compiled with debugging enabled, a sixth value can be specified to set the debug level. 

All the parameters are as described at the top of this section, and the reconnect value allows device disconnect/reconnect if a 
nonzero value is used. A sample usage is as follows: 

ahal52x=0x340,11,7,1 

N ote that the parameters must be specified in order, meaning that if you want to specify a parity setting, then you must 
specify aniobase, i rq,scsi-id, and reconnect value as wel I. 

ADAPTEC AHA154X CONFIGU RATION 

Theahal542 series cards have an i82077 floppy controller on board, whereas the ahal540 series cards do not. These are bus¬ 
mastering cards and have parameters to set the "fairness" that is used to share the bus with other devices. The boot arg looks 
like the following: 

ahal 542=i obase[,buson,busoff [, d ma speed]] 

Valid i obase values are usually one of 0x130,0x134,0x230,0x234,0x330, or 0x334. C lone cards may permit other values. 

T he bus on and bus of f values refer to the number of microseconds that the card dominates the ISA bus. The defaults are 11 us 
on and 4us off so that other cards (such as an ISA LAN CE Ethernet card) have a chance to get access to the ISA bus. 

T he d mas peed value refers to the rate (in M B/s) at which the DM A (Direct M emory Access) transfers proceed. The default is 
5M B/s. N ewer revision cards allow you to select this value as part of the soft-configuration; older cards use jumpers. You can 
use values up to 10M B/s, assuming that your motherboard is capable of handling it. Experiment with caution if using values 
over5M B/s. 
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ADAPTEC AHA274X, AHA284X, AIC7XXX CONFIGURATION 

These boards can accept an argument of the form: 

aic7xxx=ext ended ,no_reset 

The extended value, if nonzero, indicates that extended translation for large disks is enabled. Theno_reset value, if nonzero, 
tel Is the driver not to reset the SC SI bus when setting up the host adapter at boot. 

BUSLOGIC SCSI H0STSC0NFIGURATION (buslogiC=) 

At present, thebuslogic driver accepts only one parameter, the I/O base. It expects that to be one of the following valid 
values: 0x130,0x134,0x230,0x234,0x330, or 0x334. 

FUTURE DOMAIN TMC-8XX, TMC-950 CONFIGURATION 

If your card is not detected at boot time you must use a boot arg of the form 
tmc8xx=mem_base ,i rq 

T he mem_ bas e value is the value of the memory-mapped I/O region that the card uses. This is usually one of the following 

values: 0XC8000, 0xca000, 0XCC000, 0xce000, 0xdc000, or 0xde000. 

PRO AUDIO SPECTRUM CONFIGURATION 

ThePAS16 uses an NC5380 SCSI chip, and newer models support jumperless configuration. The boot arg is of the form 

pasl 6=i 0 ba s e,i r q 

The only difference is that you can specify an IRQ value of 255, which tells the driver to work without using interrupts 
albeit at a performance loss. The i 0 base is usually 0x388. 

SEAGATE ST-OX CONFIGURATION 

If your card is not detected at boot time you must use a boot arg of the form 
st 0 x=mem_base ,i r q 

T he mem_ bas e value is the value of the memory-mapped I/O region that the card uses. This is usually one of the following 

values: 0XC8000, 0xca000, 0XCC000, 0xce000, 0xdc000, or 0xde000. 

TRANTORT128 CONFIGURATION 

These cards are also based on theN CR5380 chip and accept the following options 

t 128 =mem_base ,i r q 

Thevalid values for mem. base are as follows: 0x1x000,0x08000,0xdc000, and 0x118000. 

CARDSTHAT DON'T ACCEPT BOOT ARGS 

At present, the following SCSI cards do not make use of any boot-time parameters. In some cases, you can hard-wi re values 
by directly editing the driver itself, if required. 

Always IN 2000, Adaptec ahal740, EAT A-D M A, EAT A-PIO, Future Domain 16xx, N CR5380 (generic), N CR53c7xxto 
N CR53c8xx, Q logic, Ultrastor (including u?4f), and Western D igital wd7000. 

HARD DISKS 

IDE DISK/CD-ROM DRIVER PARAMETERS 

ThelDE driver accepts a number of parameters, which rangefrom disk geometry specificationsto support for broken 
controller chips. D rive specific options are specified by using hdx= with x in a-h. 

N on-dri ve-specific options are specified with the prefix hd=. N ote that usi ng a drive-specific prefix for a non-drive-specific 
option will still work, and theoption will just be applied as expected. 
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Also note that hd= can be used to refer to the next unspecified drive in the (a,h) sequence. For the foil owing discussions, 
the hd= option will be cited for brevity. See the file readme, ide in unux/drivers/biock for more details. 

THEhd=cyls,heads,sects[ ,wpcom[,irq] ] OPTIONS 

T hese options are used to specify the physical geometry of the disk. 0 nly the first three values are required. T he cylinder, 
head, and sectors values are those used by fdisk. The write precompensation value is ignored for ID E disks. The IRQ value 
specified is the IRQ used for the interface that the drive resides on and is not really a drive-specific parameter. 

THE hd=serialize OPTION 

The dual IDE interface CM D-640 chip is broken as designed such that when drives on the secondary interface are used at 
the same time as drives on the primary interface, itwill corrupt your data. U sing this option tells the driver to makesurethat 
both interfaces are never used at the same time 

THE hd=dtc2278 OPTION 

This option tells the driver that you have a DTC-2278D IDE interface. The driver then tries to do DTC-specific operations 
to enable the second interface and to enable faster transfer modes. 

THE hd=nopnobe OPTION 

Do not probe forthisdrive. The followingline 

hdb=noprobe hdb= 1166 , 7,17 

disables the probe but still specifies the drive geometry so that it is registered as a valid block device and hence usable. 

THEhd=nowerr OPTION 

Some drives apparently have the wrerr stat bit stuck on permanently. This enables a work-around for these broken devices. 
THE hd=cdnom OPTION 

This tells the ID E driver that there is an AT API compatible CD-ROM attached in place of a normal IDE hard disk. In most 
cases, theCD-ROM isidentified automatically, but if it isn't, then thismighthelp. 

STANDARD ST-506 DISKDRIVER OPTIONS (hd=) 

The standard disk driver can accept geometry arguments for the disks similar to the ID E driver. N ote however that it only 
expects three values (c/h/s); any more or any less and itwill silently ignore you. Also, it only accepts hd= as an argument; hda= 
and so on are not valid here. The format isas follows: 

hd=cyl s ,heads ,sects 

If there are two disks installed, the preceding line is repeated with the geometry parameters of the second disk. 

XT DISKD RIVER OPTIONS (xd=) 

If you are unfortunate enough to be using one of these old 8-bit cards that move data at a whopping 125K B/s, then here is 
the scoop. If the card is not recognized, you must use a boot arg of theform 

xd=t ype,i r q, i obase ,dma_chan 

T he t y pe value specifies the particular manufacturer of the card, and you use one of the following: @=generic, i=DTC, 2 , 3 , 
4=Western D igital, 5, 6 , 7=Seagate, or 8=0 M Tl. The only difference between multiple types from the same manufacturer is 
the BIOS string used for detection, which is not used if the type is specified. 

T he xd_setup () function does no checking on the values and assumes that you entered all four values. Don't disappoint it. 

H ere is a sample usage for a WD1002 controller with the BIOS disabled or removed, using the default XT controller 
parameters: 


xd= 2 , 5 , 0 x 320,3 
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CD-ROMS (NON-SCSI/ATAPI/IDE) 

THE AZTECH INTERFACE 

The syntax for this type of card is 
aztcd=i obase [,magi c number ] 

If you set the magi c. number to 0x79, the driver will run anyway in the event of an unknown firmware version. All other values 
are ignored. 

THE CDU-31A AND CDU-33A SONY INTERFACE 

ThisCD-RO M interface is found on some of the Pro Audio Spectrum sound cards and other Sony supplied interface cards. 
The syntax is as follows: 

cdu 31 a=i obase,[i rq [ ,is_pas_card ]] 

Specifying an IRQ value of 0 tells the driver that hardware interrupts aren't supported (as on some PAS cards). If your card 
supports interrupts, you should use them because they cut down on theCPU usage of the driver. 

T he i spas, card should be entered as pas if using a Pro Audio Spectrum card; otherwise, it should not be specified at all. 

THE CDU-535 SONY INTERFACE 

The syntax for this CD-ROM i nterface is 

sonycd 535 =i obase [ ,i r q ] 

A 0 can be used for the I/O base as a placeholder if you want to specify an I RQ value. 

THE GOLDSTAR INTERFACE 

The syntax for this CD-ROM i nterface is 

gscd=i obase 

THE MITSUMI STANDARD INTERFACE 

The syntax for this CD-ROM i nterface i s 

mcd=i obase, [i rq [,wai t val ue ]] 

The wait value is used as an internal ti me-out value for people who are having problems with thei r drive and may or may 
not be implemented depending on acompile-time#define. TheM itsumi FX400 isan IDE/ATAPI CD-ROM player and 
does not use themed driver. 

THE MITSUMI XA/MULTI SESSION INTERFACE (mcdx=) 

At present, this experimental driver has a setup function, but no parameters are implemented (as of 1.3.15). This is for the 
same hardware as previously described, but the driver has extended features. 

THE OPTICS STORAGE INTERFACE 

The syntax for this type of card is 
optcd=i obase 

THE PHILLIPS CM206 INTERFACE 

The syntax for this type of card is 
cm 206 =[i obase ][ ,i r q ] 

The driver assumes numbers between 3 and 11 are IRQ values and numbers between 0x300 and 0x370 are I/O ports, so you 
can specify one, or both numbers, in any order. It also acceptscm 206 =auto to enable autoprobing. 
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THE SANYO INTERFACE 

The syntax for this type of card is 
sjcd=i obase [,i rq [,dma_channel ] ] 

THE SOUNDBLASTER PRO INTERFACE 

The syntax for this type of card is 
sbpcd=i obase ,type 

type is one of the following (case-sensitive) strings: SoundBlaster, LaserMate, or spea. The I/O base is that of the C D-ROM 
interface and not that of thesound portion of thecard. 

ETHERNET DEVICES 

D ifferent drivers use different parameters, but they all at least share having an IRQ, an I/O port base value, and a name. In 
its most generic form, it looks something like this: 
ether=i rq ,i obase [,param_l [,param_2,.. .param_8 ]],name 

The first non-numeric argument is taken as the name. The para m_n values (if applicable) usually have different meanings for 
each different card or driver. Typical par am_n values are used to specify things such as shared memory address, interface 
selection, DMA channel, and the like. 

The most common use of this parameter is to force probing for a second ethercard because the default is to only probe for 

one. This can be accomplished with a simple 

ether=0,0,eth1 

N otethat the values of 0 for the IRQ and I/O base in the example tel I the drivers to autoprobe 

The Ethernet H owTo has extensive documentation on using multiple cards and on the card-specific or driver-specific 
implementation of the para m_n values where used. Interested readers should refer to the section in that document on their 
particular card. 

THE FLOPPY DISK DRIVER 

There are many floppy driver options, and they are all listed in readme. fd in linux/drivers/biock. Thisinformation istaken 
directly from that file. 

floppy=mask,allowed_drive_mask 

Sets the bitmask of allowed drives to mask. By default, only units 0 and 1 of each floppy controller are allowed. This is done 
because certain non-standard hardware (ASU S PCI motherboards) mess up the keyboard when accessing units 2 or 3. This 
option is somewhat obsolete because of the cmos option. 

floppy=all drives 

Sets the bitmask of allowed drives to all drives. U sethis if you have more than two drives connected to a floppy controller. 

floppy=asus_pci 

Sets the bitmask to allow only units 0 and 1 (the default). 

floppy=daring 

Tel Is the floppy driver that you have a well-behaved floppy controller. T his allows more efficient and smoother operation but 
may fail on certain controllers. This can speed up certain operations. 

floppy=0,daring 

Tel Is the floppy driver that your floppy controller should be used with caution. 
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floppy=one_fdc 

T el Is the floppy driver that you have only one floppy controller (default), 

floppy=two_fdc 0 R floppy=address,two_fdc 

T el Is the floppy driver that you have two floppy controllers. The second floppy controller is assumed to beat address. If 
address is not given, 0x370 is assumed. 

floppy=thinkpad 

T el Is the floppy driver that you have a Thinkpad. Thinkpads use an inverted convention for the disk change line, 

floppy=0,thinkpad 

T ells the floppy driver that you don't haveaThinkpad. 

floppy=drive,type,cmos 

Setsthecmos typeof drive to type. Additionally, this drive isallowed in the bitmask. This is useful if you have more than two 
floppy drives (only two can be described in the physical cmos), or if your BIOS uses non-standard cmos types. Setting the cmos 
to 0 for the first two drives (default) makes the floppy driver read the physical cmos for those drives. 

floppy=unexpected_intennupts 

Print a warning message when an unexpected interrupt is received (default behavior) 

floppy=no unexpected_interrupts OR floppy=L40SX 

Don't print a message when an unexpected interrupt is received. This is needed on IBM L40SX laptopsin certain video 
modes. (There seems to bean interaction between video and floppy. The unexpected interrupts only affect performance and 
can safely be ignored.) 

THE SOUND DRIVER 

The sound driver can also accept boot argsto override the compiled in values. This is not recommended because it is rather 
complex. It is described in the Readme. Linux file in linux/drivers/sound. It accepts a boot arg of the form 
sound=devi cel[,devi ce2 [,devi ce3 ...[,devi cell ]]] 

Each devi ceN value is of theformat oxTaaa i d and the bytes are used asfollows: 
t— device type i=fm, 2=sb, 3=pas, 4=gus, 5=mpu40i, 6=sbi6, and 7=sbi6-mpu40i 
aaa— I/O address in hex 
i — interrupt line in hex ( 10 ^, 11 =b,...) 
d—DMA channel 

As you can see, it gets pretty messy, and you are better off to compile in your own personal values as recommended. Using a 
boot arg of sound =0 disables the sound driver entirely. 

THE BUS MOUSE DRIVER (bmouse=) 

T he busmousedriver only accepts one parameter, the hardware IRQ value to be used. 

AUTHORS 

LinusTorvalds(and many others) 

SEE ALSO 

klogd(8), lilo.conf(5), lilo(8), mount(8), rdev(8) 

This man page was derived from the Boot Parameter HOWTO (version 1.0.1) written by Paul Gortmaker. M ore informa¬ 
tion can be found in this (or a more recent) HOWTO. 


Linux 1.3.19,15 August 1995 
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grotf_me 

groffjne— troff macros for formatting papers. 

SYNOPSIS 

groffjne [ options ] file ... 
troffjne [ options ] file ... 

DESCRIPTION 

This manual page describes the GN U version ofthe_me macros, which is part of the groft document formatting system. 
This version can be used with both GNU troff and UN IX troff. This package of troff macro definitions provides a canned 
formatting facility for technical papers in various formats. 

The macro requests are defined as follows. M any troff requests are unsafe in conjunction with this package; however, these 
requests can be used with impunity after the first .pp: 


bp 

Begin new page 

br 

Break output line here 

sp n 

Insert n spacing lines 

Is n 

Linespacing; n=i single, n =2 double space 

na 

N o alignment of right margin 

ce n 

Center nextn lines 

ul n 

Underline next n lines 


Output of the pic, eqn, refer, and tbi preprocessors is acceptable as input. 

FILES 

/usr/lib/groff/tmac/tmac.e 

SEE ALSO 

groff(l), gtroff(l), jne Reference M an ual, Eric P. Allman, Writing Papers with Groff Using me 

REQUESTS 

This list is incomplete; seethe_me Reference M anual for interesting details 


Request 

Initial Value 

Cause Break 

Explanation 

■ (c 

- 

Yes 

Begin centered block. 

■ (d 

- 

N o 

Begin delayed text. 

■ (f 

- 

N o 

Begin footnote. 

■ 0 

- 

Yes 

Begin list. 

■(q 

- 

Yes 

Begin major quote. 

.(XX 

- 

N o 

Begin indexed item in index 

.(Z 

- 

N o 

Begin floating keep. 

■ )C 

- 

Yes 

End centered block. 

■ )d 

- 

Yes 

End delayed text. 

■ )f 

- 

Yes 

End footnote. 

■ )1 

- 

Yes 

End list. 

■ )q 

- 

Yes 

End major quote. 


continues 
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Request 

Initial Value 

Cause Break 

Explanation 

■ )x 

- 

Yes 

End index item. 

■ )Z 

- 

Yes 

End floating keep. 

.++ m H 


N o 

Define paper section. 

m defines the part of the paper and can bee 
(chapter), a (appendix), p (preliminary, such as 
abstract, table of contents, and so on), b (bibliogra¬ 
phy), rc (chapters renumbered from page one each 
chapter), or ra (appendix renumbered from page 
one). 

.+c T 

- 

Yes 

Begin chapter (or appendix and so on asset by.++). 
T is the chapter title. 

.1c 

1 

Yes 

0 ne column format on a new page. 

.2c 

1 

Yes 

Two column format. Equation number isy. 

.EN 

- 

Yes 

Space after equation produced byeqn orneqn. 

.EQ x y 


Yes 

Precede equation; break out and add space. 

The optional argument x may be i to indent 
equation (default), l to left-adjust the equation, ore 
to center the equation. 

.GE 

- 

Yes 

End gremlin picture. 

.GS 

- 

Yes 

Begin gremlin picture. 

.PE 

- 

Yes 

End pic picture. 

.PS 

- 

Yes 

Begin pic picture. 

.TE 

- 

Yes 

End table. 

.TH 

- 

Yes 

End heading section of table. 

.TS x 

- 

Yes 

Begin table; if* is h, table has repeated heading. 

.b x 

N o 

N o 

Print x in boldface; if no argument switch to 
boldface. 

.ba +n 

0 

Yes 

Augments the base indent by n. 

This indent is used to set the indent on regular text 
(like paragraphs). 

.be 

N o 

Yes 

Begin new column. 

.bi x 

N o 

N o 

Print x in bold italics (no fill only). 

.bu 

- 

Yes 

Begin bulleted paragraph. 

.bx x 

N o 

N o 

Print x in a box (no fill only). 

.ef 1 x' y 1 z ' 

■■ 

N o 

Set even footer to x y z. 

.eh 1 x'y'z 1 

■■ 

N o 

Set even header to x y z. 

.fo 'x 'y 'z 1 

■■ 

N o 

Set footer to x y z. 

.hx 

- 

N o 

Suppress headers and footers on next page. 

.he 1 x'y 1 z ' 

■■ 

N o 

Set header to * y z. 

.hi 

- 

Yes 

Draw a horizontal line. 

.i x 

N o 

N o 

Italicize*; if x ismissing, italic text follows. 

■ip x y 

N o 

Yes 

Start indented paragraph with hanging tag*. 
Indentation isy ens(default is 5 ). 
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Request 

Initial Value 

Cause Break 

Explanation 

•IP 

Yes 

Yes 

Start left-blocked paragraph. 

.np 

1 

Yes 

Start numbered paragraph. 

.of 1 x' y 1 z ' 

■■ 

N o 

Set odd footer to x y z. 

.oh 1 x'y 1 z ' 

■■ 

N o 

Set odd header to x y z. 

■Pd 

- 

Yes 

Print delayed text. 

■PP 

N o 

Yes 

Begin paragraph. First line indented. 

. r 

Yes 

N o 

Roman text follows. 

.re 

- 

N o 

Reset tabs to default values. 

.sh n x 

- 

Yes 

Section head follows; font is automatically bold, n is 
level of section, x istitle of section. 

.sk 

N o 

N o 

Leave the next page blank. 0 nly one page is 
remembered ahead. 

.sm x 

- 

N o 

Set x in a smaller poi nt size. 

.sz +n 

lOp 

N o 

Augment the point size by n points 

■tp 

N o 

Yes 

Begin title page. 

.u X 

- 

N o 

Underline argument (even in troff) (nofill only). 

.uh 

- 

Yes 

Like .sh but unnumbered. 

.xp X 

- 

N o 

Print indexx. 


Groff Version 1.09, 6 August 1992 
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groffjnm— groff mm macros. 

SYNOPSIS 

groff_mgm [ options... ] [files... ] 

DESCRIPTION 

Thegroff mm macros are intended to be compatible with theDWB mm macros with the following limitations 

N o letter macros are implemented (yet). 

N o Bell Labs localisms are implemented. 

T he macros ok and pm are not implemented. 

groft mm does not support cut marks 

mgm is intended to be international. Therefore it is possible to write short national macro-files that change all English text to 

the preferred language. Usemgmse as an example. 

groff mm hassa/eral extensions 

ic [i] Begin onecolumn processing. A i as argument disables the page break. 

app name text Begin an appendix with the name name . Automatic naming occurs if name is T he 

appendixes starts with A if auto is used. A new page is ejected, and a header is also 
produced if the number variable Aph is non-zero. This is the default. T he appendix 
always appear in the I ist of contents with the correct page number. T he name 
appendix can be changed by setting the string App to the desired text. 
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APPSK name pages text 


B 1 

B 2 

BVL 

COVER [arg ] 


COVEND 

GETHN r ef name [var name ] 

GETPN r ef name [var name ] 

GETR r ef name 

GETST r ef name [var name ] 

INITR f i I ename 


MC column-size [col umn-separ at i on ] 
MT [arg [addressee]] 


MOVE y- pos [x-pos [I i ne-l ength]] 


Same as .app, but the page number is incremented with pages. This is used 
when diagrams or other non-formatted documents areincluded as appen¬ 
dixes. 

Begin boxfasthems macro) Drawsabox around the text. 

End box. Finish the box. 

Start of broken variable-item list. Like vl but text begins always at the next 
line 

cover begi ns a coversheet definition. It is important that .cover appears 
before any normal text, .cover uses ar g to build thefilename /usr/iib/groff / 
tmac/mm/arg.cov. Therefore, it is possibleto create unlimited types of 
coversheets. ms.cov issupposed to look like the ms coversheet. .cover requires 
a .covend attheend of the cover definition. Always use this order of thecover 
macros: 

.COVER 

.TL 

.AF 

■ AU 

.AT 

.AS 

.AE 

.COVEND 

H owever, only .tl and .au are required. 

Thisfinishesthe cover description and prints the cover page. It isdefined in 
the cover file. 

Includes the header number where the correspond! ngsETR ref name was 
placed. Will bex.x.x. in passl. See initr. If varname isused, gethn sets the 
string variable# ar name to the header number. 

I ncludes the page number where the corresponding setr r ef na me was placed. 
Will be 9999 in pass 1. See initr. If var name isused, getpn sets the string 
variable^ r name to the page number. 

Combines gethn and getpn with the text 'chapter 1 and ', page 1 . The string 
Or f contains the text for reference: .ds Qrf See chapter \\*[Qrfh], page 
\\* [Qr f p ] . Qr f may be changed to support other languages. Strings Qrf h and 
Orf p are set by getr and contain the page and header number. 

I ncludes the string saved with the second argument to .setr. Will be dummy 
string in passl. I f v a r n a me is used, getst sets the string variable va r name to the 
saved string. See initr. 

Initialize the reference macros. References will be written to f i i ename. tmp 
and f i i ename .qrf. Requirestwo passes with groff. The first looks for 
references and thesecond includes them, initr can be used several times, but 
it is only the first occurrence of initr that is active. See also setr, getpn, and 

GETHN. 

Begin multiple columns. Return to normal with ic. 

M emorandum type. T he a r g is part of a filename in /usr/iib/groff/tmac/mm/ 

* .mt. M emorandum type 0 through 5 are supported, including st r i ng. 
addressee just sets a variable, used in the AT&T macros. 

M ove to a position, page offset set to x-pos . Ifi i ne-i ength is not given, the 
difference between the current and new page offset is used. U se pgform 
without arguments to return to normal. 



MULB cwl spacel [cw 2 space 2 [cw 3 ...]] 


MULN 

MULE 

PGFORM [I i nel ength[pagel ength [pageoffset [ 1 ]]]] 
I i nel ength, pagel ength and/or pageoffset. 

PGNH 

SETR r ef name [string] 


VERBON [fI ag [poi ntsi ze [font ]]] 


VERBOFF 

N ew variables in mgm: 

App 

Aph 
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Begin a special multi-column mode. Every column's width must 
be specified. Also, the space between the columns must be 
specified. The last column does not need any space definition. 
mulb starts a diversion and mule ends the diversion and prints the 
columns. The unit for width and space isn, but mulb accepts all 
normal unit specifications such asc and i. mulb operatesin a 
separate environment. 

Begin the next column. Thisistheonly way to switch columns. 
End the multi-column modeand print the columns. 

This macro can be used for special formatting, such as pgform 
letterheads. Sets can be used without arguments to reset 
everything after a move. A line break is done unless the fourth 
argument is given. This can be used to avoid the page number 
on the first page whilesetting new width and length. 

N o header is printed on the next page. Used to get rid of the 
header in letters or other special texts. This macro must be used 
before any text to inhibit the page header on the first page. 
Remember the current header and page number as ref name. Saves 
string if str i ng is defined, string is retrieved with .getst. See 

INITR. 

Reset tabs to every 5n. Usually used to reset any previous tab 
positions. 

Begin verbatim output using Courier font. Usually for printing 
programs. All characters have equal width. T he point size can be 
changed with thesecond argument. By specifying thefont 
argument, itispossibleto use another font instead of Courier, 
flag controls several special features. It contains the sum of all 
wanted features: 

Value Description 

1 D isable the escape-character (n). T his is usually 
turned on during verbose output. 

2 Add an empty linebeforetheverbosetext. 

4 Add an empty line after the verbose text. 

8 Printtheverbosetextwith numbered lines.This 

adds four digit-sized spaces in the beginning of 
each line. Finer control isavailablewith the 
stri ng-vari able verbnm. It contains all arguments 
to thetrotf-command .™, usually i. 

is Indent the verbose text with fivens Thisis 

controlled by thenumber-variableverbin (in 
units). 

End verbati m output. 

A string containing the word appendix. 

Print an appendix page for every new appendix if this number 
variable is nonzero. No output will occur if Aph is zero, but there 
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will always be an appendix entry in the list of contents 

Hps 

N umber variable with the headi ng pre-space level . 1 f the headi ng 
level is less than or equal to Hps, then two lines precede the section 
heading instead of one. D efault is first level only. T he real amount 
of lines is controlled by the variables Hpsi andHps2. 

Hpsl 

This isthe number of lines preceding .Hwhen the heading level is 
greater than Hps. Value is in units, usually o.5v. 

Hps2 

This isthe number of lines preceding .Hwhen the heading level is 
less than or equal to Hps. Value is in units, usually iv. 

Lifg 

String containing figure. 

Litb 

String containing table. 

Liex 

String containing exhibit. 

Liec 

String containing equation. 

Licon 

String containing contents. 

Lsp 

The size of an empty line. Usually o.5v, but it is i v if n is set 


( . nroff). 

M01 - M012 

Stri ngs contai ni ng J anuary to D ecem ber. 

Qrf 

String Containing “See chapter \\*[Qrfh], page \\n[Qrf p] . ". 

Pgps 

Controls whether header and footer point size should follow the 
current setting or just change when the header and footer is 
defined. 


Value Description 

0 Pointsizewill only change to the current setti ng 


when .ph, .pf, .oh, .eh, .of, or .oe isexecuted. 


i Pointsizewill change after every .s. Thisisthe 

default. 

Sectf 

Flag controlling section figures. A nonzero value enables this. See 
also register N . 

Sectp 

Flag controlling section page numbers. A nonzero value enables 
this See also register N . 

.mgm 

Always 1. 

A file called locale or langjocaie is read after the initiation of the global variables. It is therefore possible to localize the 

macroswith a company nameand so on. 

The foil owing standard macros are implemented: 


2C 

Begin two column processing. 

AE 

Abstract end. 

AF [na me of firm] 

Author's firm. 

AL [t ype [t ext - i ndent [ 1 ] ] ] ] 

Start autoincrement list. 

AS [arg [indent]] 

Abstract start. Indent is specified in ens, but scaling is allowed. 

AST [title] 

Abstract title D efault is 'abstract 1 . 

AT ti tl el [t i 11 e 2 .. .] 

Author's title. 

AU n a me [initials [ 1 o c [dept 

[ext [room [arg [arg 

[arg] ]]]]]]] Author information. 

B [bol d-text [prev-font-text [...]]] 

Begin boldface. No limit on the number of arguments 



BE 

BI [bol d-text [italic-text [bold-text [...]]] 
BL [text- i ndent [ 1 ]] 

BR [bold-text [roman-text [bold-text [...]]] 

BS 

DE 

DF[f or mat [fill [r i ndent ] ] ] 

DL [text- i ndent [ 1 ]] 

DS [for mat [fill [r i ndent ]] ] 

EC [title [over r i de [f I ag [refname]]]] 

EF [arg] 

EH [arg ] 

EN 

EQ [I abel ] 

EX [title [over r i de [f I ag [refname]]]] 

FD [arg [ 1 ]] 

FE 

FG [title [over r i de [f I ag [refname]]]] 

FS 

H level [headi ng-text [headi ng-suffi x]] 

HC [hyphenation-character] 

HM [argl [a r g 2 [... [a r g 7 ] ] ] ] 

HU headi ng- 1 ext 
HXdlevel rlevel heading-text 
HYdlevel rlevel heading-text 
HZdlevel rlevel heading-text 
I [i t al i c-1 ext . 

IB [i t al i c -1 ext 

IR [i t al i c -1 ext 

LB t ext ■ i ndent ma r k-i ndent 

LC [I i st level] 

LE 

LI [mark [ 1 ]] 

ML mark [text- i ndent ] 

MT [arg [addressee]] 


groff_mm 

End bottom block. 

Bold italic. N o limit on the number of arguments. 

Start bullet list. 

Bold roman. N o limit on the number of arguments. 

Bottom block start. 

Display end. 

Begin floating display (no nesting allowed). 

Dash list start. 

Static display start. Can now haveunlimited nesting. Also, right- 
adjusted text and block may beused (r or rb as format). 

Equation title. If ref name is used, then the equation number is 
saved with .setr andean be retrieved with .getst ref name. 

Even page footer. 

Even page header. 

Equation end. 

Equation start. 

Exhibit title. If ref name is used, then the exhibit number is saved 
with .setr andean be retrieved with .GETSTrefname. 

Footnote default format. 

Footnote end. 

Figure title. If refname isused, then thefigurenumber issaved 
with .setr andean be retrieved with .GETSTrefname. 

Footnote start. Footnotesin displays isnow possible. 

N umbered heading. 

Set hyphenation character. 

FI eading mark style. 

Unnumbered header. 

User-defined heading exit. Called just before printing the header. 
User-defined heading exit. Called just before printing the header. 
User-defined heading exit. Called just after printing the header. 

[pr ev- font-text 

[italic-text [...]]] Italic. 

[bol d-text 

[italic-text [...]]] Italic bold. 

[ r o ma n -1 e x t 

[italic-text [...]]] Italic roman, 

pad type[mark 

[Li-space [lb- space ]]] Listbegin macro. 

List status clear. 

List end. 

List item. 

M arked list start. 

M emorandum type. See above note about mt. 
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ND new- dat e 
OF [arg] 

OH [arg] 

OP 

P [type] 

PE 

PF [arg] 

PH [arg ] 

PS 

PX 

R 

RB [roman-text [bold-text 

RD [prompt [di versi on [string]]] 
RF 

RI [roman-text 


RL [text- i ndent [ 1 ]] 
RP [arg [arg]] 

RS [st r i ng - na me ] 

S [si ze [spacing]] 


SA [arg] 

SK [pages ] 

SM stri ngl [stri ng 2 [st ri n g 3 ] ] 

SP [I i nes ] 

TB [title [over r i de [f I ag [refname]]]] 
TC [si evel [spaci ng 


TE 

TH [N] 

TL 

TM [numl [num 2 [...]]] 


TP 

TS [H] 

TX 

TY 


N ew date. 

0 dd page footer. 

Odd page header. 

Skip to odd page. 

Begin new paragraph. 

Picture end. 

Page footer. 

Page header. 

Picture start (from pic). 

Page header user-defined exit. 

Roman. 

[roman-text [...]]] Roman-bold. 

Read to d i versi on an d/or stri ng. 

Reference end. 

[i t a I i c -1 ext 

[roman-text [...]]] Roman italic. 

Reference list start. 

Produce reference page. 

Reference start. 

Set pointsizeand vertical spacing. If any argument equalsp, then the 
previous value is used. A c means current value, and d means default 
value. If + or - is used before the value, an increment or decrement of 
the current value is done. 

Set adjustment. 

Skip pages. 

Make a string smaller. 

Space vertically, i i nes can have any scaling factor, such as3i or 8 v. 
Table title. If ref name is used, then the table number is saved with 
.setr and can be retrieved with .getst ref name. 

[t I evel [tab [hi [h 2 
[h 3 [h 4 [h 5 ]]]]]]]] ] 

Table of contents. All texts can be redefined, new string variables 
Lifg, Litb, Liex, Liec, and Licon Contain "Figure", "TABLE", "Exhibit", 
"Equation", and "contents" . T hese can be redefined to other 
languages. 

Table end. 

Table header. 

Begin title of memorandum. 

Technical memorandum numbersused in .mt. Unlimited number of 
arguments may be given. 

Top of page user-defined macro. N otethat header and footer is 
printed in a separate environment. Line length ispreserved. 

T able start. 

User-defined table of contents exit. 

U ser-defined table of contents exit (no "contents" ). 
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VL [text-indent [mark-indent [1]]] 
VM [top [bottom]] 

WC [f or mat ] 

Strings used in mgm: 

EM 

HF 

HP 

Lf 

Lt 

Lx 

Le 

Rp 

Tm 

N umber variables used in mgm: 

Cl =2 

Cp =0 

D =0 


De =0 

Df =5 

Ds =1 

E j =0 

Eq =0 

Fs =1 

HI - H 7 

Hb =2 

Hc =0 

Hi =1 


Hs =2 

Ht =0 

Hu =2 

Hy =1 

Lf= 1 , Lt= 1 , Lx= 1 , Le =0 

Li=6 

Ls =99 

N =0 


Variable-item list start. 

Vertical margin. 

Footnote and display width control. 


Em dash string. 

Font list for headings, usually "2 22222 2 11 . Nonnumeric font 
names may also be used. 

Pointsize list for headings. Usually "0 00000 0 -, which isthe 
sameas n i 0 10 10 10 10 10 10 ". 

Contains "list of figures 11 . 

Contains "list of tables 11 . 

Contains "list of exhibits". 

Contains "list of equations - . 

Contains "REFERENCES". 

Contains \ (tm, trademark. 


Contents level [0:7]; contents saved if heading level <=ci. 

Eject page between list of xxxx if cp == 0 . 

D ebug flag, values greater than 0 produce varyi ng degree of debug. A 
value of 1 gives information about the progress of formatting. 

Eject after floating display is output [0:1], 

Floating keep output [0:5], 

Space before and after display if =1 [0:1], 

Eject page. 

Equation label adjust 0 =left, i=right. 

Footnote spacing. 

H eading counters. 

H eading break level [0:7], 

H eading centering level [0:7], 

FI eading temporary indent [0:2], @isno indent, left margin. 1 is 
indent to right, like .p 1.2 is indent to lineup with text part of 
preceding heading. 

FI eading space level [0:7] 

H eading numbering types is multiple ( 1 . 1 . 1 ...). 1 is single. 
Unnumbered heading level. 

Hyphenation in body. 0 is no hyphenation. 1 is hyphenation 14 on. 
Enables ( 1 ) or disables ( 0 ) the printing of a list of figures, list of tables, 
list of exhibits, and list of equations. 

List indent, used by .al. 

List space if current list level isgreaterthan ls, then no spacing 
occurs around lists. 

N umbering style [0:5]: 

0 = (D efault) N ormal header for all pages. 

1 = H eader replaces footer on first page; header is empty. 

2 =Page header isremoved on thefirst page. 
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3 =Section page numbering enabled. 

4 = Page header is removed on the first page. 

5 = Section page and section figure numbering enabled. See also the 
number register sectf and sectp. 

Np=0 

N umbered paragraphs. 0 is not numbered. 1 is numbered in first-level 
headings. 

Of=0 

Format of figure, table, exhibit, and equation titles. 0 is". ■. 1 is 

P 

Current page number, usually the same as % unless section-page 
numbering is enabled. 

Pi=5 

Paragraph indent. 

Ps=1 

Paragraph spacing. 

Pt=0 

Paragraph type 0 is left-justified. 1 isindented . p. 2 is indented .p 
except after .h, .de, or .le. 

Si=5 

D isplay indent. 

AUTHOR 



Jorgen H agg, Lund Institute of Technology, Sweden (jh@efd.ith.se). 

FILES 

/usr/lib/groff/tmac/tmac. gm 
/usr/lib/groff/tmac/mm/*.cov 
/usr/lib/groff/tmac/mm/*.MT 
/usr/lib/groff / tmac/mni/locale 



SEE ALSO 

groff(l), gtroff(l), gtbl(l), gpic(l), geqn(l), mm(7), mgmse(7) 


Groff Version 1.09,14 February 1994 
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groff_ms— groff ms macros. 

SYNOPSIS 

groff_mgs [ options... ] [files... ] 

DESCRIPTION 

This manual page describes the GN U version of the ms macros which is part of the groff document formatting system. The 
groff ms macros are intended to be compatible with the documented behavior of the 4.3 BSD U NIX ms macros, subject to 
thefollowing limitations: 

The internals of groff ms are not similar to the internals of UNIX ms, so documents that depend upon implementation 
details of U NIX ms might not work with groff ms. 

T here is no support for typewriter-like devices. 

Berkeley localisms in particular the tm and ct macros, are not implemented, 
groff ms does not provide cut marks 

M ultiple line spacing isnot allowed. (U sea larger vertical spacing instead.) 
groff ms does not work in compatibility mode (such as with the -c option). 
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The error-handling policy of groft ms is to detect and report errors, rather than silently ignore them. 

Thegrotf ms macros use many features of G N U troft and therefore cannot be used with any other troff. 

Bell Labs localisms are not implemented in either theBSD ms macrosor in thegrotf ms macros. 

SomeU NIX ms documentation says that the cw and gw number registers can beused to control the column width and gutter 
width. T his is not the case. T hese number registers are not used in groft ms. 

M acrosthat cause a reset set the indent. M acrosthat change the indent do not increment or decrement the indent, but rather 
set it absolutely. This can cause problems for documents that define additional macros of their own. The solution is to not 
use the in request but instead to use the rs and re macros. 

The number register gs is set to i by thegroff ms macros but is not used by theU NIX ms macros. It is intended that 
documents that need to determine whether they are being formatted with U NIX ms orgroff ms use this number register. 

Footnotes are implemented so that they can safely beused within keeps and displays. Automatically numbered footnotes 
within floating keeps are not recommended. It is safe to have another \** between a \** and the corresponding . fs; it is 
required only that each .fs occur after the corresponding \** and that the occurrences of .fs are in the same order as the 
corresponding occurrences of \**. 

The strings \*{ and \*j can beused to begin and end a superscript. 

SomeU NIX V10 ms features are implemented. The b, i, and bi macroscan have an optional third argument that is printed 
in the current font before the first argument. There is a macro cw like b that changes to a constant-width font. 

The following strings can be redefined to adapt thegroff ms macros to languages other than English: 


String 

Default Value 

REFERENCES 

References 

ABSTRACT 

ABSTRACT 

TOC 

Table of Contents 

MONTH1 

January 

M0NTH2 

February 

M0NTH3 

March 

M0NTH4 

April 

M0NTH5 

May 

M0NTH6 

June 

M0NTH7 

July 

M0NTH8 

August 

M0NTH9 

September 

MONTH10 

October 

MONTH11 

November 

M0NTH12 

December 


The font family is reset from the string fam; at initialization if this string is undefined, it is set to the current font family. The 
pointsize, vertical spacing, and inter-paragraph spacing for footnotes are taken from the number registers fps, fvs, and fpd; 
at initialization, these are set to \n(Ps-2, \n[FPS]+2, and \n(PD/2; however, if any of these registers was defined before 
initialization, it is not set. The hyphenation flags (as set by the .hy request) are set from theHY register; if this was not defined 
at initialization, it isset to 14 . 

Right-aligned displays are available with .ds Rand .rd. 

The following conventions are used for names of macros, strings, and number registers. External names avail able to 
documents that use thegroff ms macroscontain only uppercase letters and digits. Internally, the macros are divided into 
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modules. N amesused only within one module are of the form modui e *na me . N amesused outside the module in which they 
are defined are of the form mo d u i e @n a me . N ames associated with a particular environment are of the former i ronment: n a me; 
these are used only within the par module, and name does not have a module prefix. Constructed names used to implement 
arrays are of the form array ii ndex. Thus, thegroff ms macros reserve the following names: 

Names containing* 

N amescontaining@ 

N ames containing: 

N ames containi ng only uppercase letters and digits 


FILES 

/usr/lib/groff/tmac/tmac.gs 

SEE ALSO 

groff(l), gtroff(l), gtbl(l), gpic(l), geqn(l), ms(7) 


Groff Version 1.09, 9 January 1994 


hier 

hier— Description of the filesystem hierarchy. 


DESCRIPTION 


A typical Linux system has, among others, thefollowing directories: 


/ 

/bin 

/boot 

/dev 
/ dos 

/etc 


/etc/skel 

/etc/X11 

/home 


/ lib 

/mnt 

/proc 


Thisistherootdi recto ry. T h i s i s wh ere the w ho le tree starts 

This directory contains executable programs that are needed in single-user mode and to 

bring the system up or repair it. 

C ontains static fi les for the boot loader. T his di rectory only holds the fi les that are 
needed during the boot process. The map installer and configuration files should go to / 
sbin and /etc. 

Special or device files that refer to physical devices. Seemknod(l). 

If both M S-DOS and Linux are run on one computer, this is a typical place to mount a 
DOS filesystem. 

Contains configuration files that are local to the machine. Some larger software 
packages, such as X11, can have their own subdirectories below /etc. Site-wide 
configuration filesmay be placed here or in /usr/etc. N evertheless, programs should 
always look for these files in /etc and you may have links for these files to /usr/etc. 
When a new user account is created, files from this directory are usually copied into the 
user's home directory. 

Configuration files for the X11 window system. 

On machines with home directories for users, these are usually beneath this directory, 
directly or not. T he structure of this di rectory depends on local administration 
decisions. 

This directory should hold those shared libraries that are necessary to boot the system 
and to run the commands in the root filesystem. 

T his is a mount point for temporarily mounted filesystems. 

Thisisa mount point for the proc filesystem, which provides information about 
running processes and the kernel. This pseudo-filesystem is described in more detail in 
proc(5). 



hier 


/ sbin 

/tmp 

/usr 

/usr/X11R6 

/usr/X11R6/bin 

/usr/X11R6/lib 
/usr/X11R6/lib/X11 

/usr/XI1R6/include/X11 

/usr/bin 

/usr/bin/X11 

/usr/dict 

/usr/etc 

/usr/include 

/usr/include/X11 

/usr/include/asm 

/usr/include/linux 

/usr/include/g++ 

/usr/lib 

/usr/lib/X11 

/usr/lib/gcc-lib 

/usr/lib/groff 

/usr/lib/uucp 

/usr/lib/zoneinfo 

/usr/local 

/usr/local/bin 

/usr/local/doc 

/usr/local/etc 

/usr/local/lib 

/usr/local/info 

/usr/local/man 

/usr/local/sbin 



Like /bin, this directory holds commands needed to boot the system but usually not 
executed by normal users. 

This directory contains temporary files that may be deleted with no notice such as by a 
regular job or at system bootup. 

T his directory is usually mounted from a separate partition. It should hold only 
sharable, read-only data so that it can be mounted by various machines running Linux. 
TheX window system, version 11, release6. 

Binaries that belong to theX window system; often, there is a symbolic link from the 
more traditional /usr/bin/xn to here. 

Data files associated with theX window system. 

These contain miscellaneous files needed to run X; Often, there is a symbolic link from 
/usr/iib/xi i to this directory. 

Contains include files needed for compiling programs using theX 11 window system. 
Often, there is a symbolic link from /usr/inciude/xn to this directory. 

This is the primary directory for executable programs. M ost programs executed by 
normal users that are not needed for booting or for repairing the system and that are not 
installed locally should be placed in this directory. 

This is the traditional place to look for X11 executables; on Linux, it usually is a 
symbolic link to /usr/xi iR6/bin. 

This directory holds files containing word lists for spell-checkers. 

Site-wide configuration files to be shared between several machines may be stored in this 
directory. However, commands should always reference those files using the/etc 
directory. Links from files in /etc should point to the appropriate files in /usr/etc. 

IncludefilesfortheC compiler. 

Include files for theC compiler and theX window system. This is usually a symbolic 

link to / usr /XI1R6/ include /X11. 

I ncludefiles that declare some assembler functions This should be a symbolic link to/ 

usr/src/linux/include/asm. 

This contains information that may change from system release to system release and 
should be a symbolic link to /usr/src/iinux/inciude/iinux to get at operating-system- 
specific information. 

I nclude files to use with theGN U C++compiler. 

Object libraries, including dynamic libraries, plus some executables that usually are not 
invoked directly. M ore complicated programs may havewholesubdirectories there. 

The usual place for data files associated with X programs and configuration files for the 
X system itself. On Linux, it usually is a symbolic link to /usr/xi iR6/iib/xi i. 

Contains executables and include fi lesfor theG N U C compiler, gcc(l). 

Files for theGN U groff document formatting system. 

Files for uucp(l). 

Files for time zone information. 

This is where programs that are local to thesite typically go. 

Binaries for programs local to the site go there. 

Local documentation. 

Configuration files associated with locally installed programs go there. 

Files associated with locally installed programs go there. 

Info pages associated with locally installed programsgo there. 

Man pages associated with locally installed programs go there. 

Locally installed programs for system administration. 
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/usr/local/src 

/usr/man 

/usr/man/cat[ 1-9] 

/usr/man/1 oca I e/man[1 -9] 

/usr/sbin 

/usr/src 

/usr/src/linux 

/usr/tmp 

/var 

/var/adm 

/var/lock 


/var/log 

/var/preserve 

/var/run 

/var/spool 

/var/spool/at 

/var/spool/cron 

/var/spool/lpd 

/var/spool/mail 

/var/spool/smail 

/var/spool/news 

/var/spool/uucp 

/var/tmp 


Source code for locally installed software. 

M an pages go in thereinto their subdirectories. 

These directories contain preformatted manual pages according to their man page 
section. 

These directories contain manual pages that are in source code form. Systems that use a 
unique language and code set for all manual pages may omit the i ocai e substring. 

This directory contains program binaries for system administration that are not essential 
for the boot process, for mounting /usr, or for system repair. 

Source files for different parts of the system. 

Thiscontainsthesourcesfor the kernel of the operating system itself. 

An alternative place to store temporary files; This should be a link to /var/tmp. 

This directory contains files that may change in size, such as spool and log files. 

This directory is superseded by /var/iog and should be a symbolic link to /var/iog. 

Lock files are placed in this directory. The naming convention for device lock files is 
lck. .devi ce where devi ce is the device's name in the filesystem. The format used is that 
ofHDU UUCP lock files—that is lock files contain a PID as a 10-byte ASC11 decimal 
number, followed by a newline character. 

M iscellaneous log files. 

Thisiswherevi(l) saves edit sessions so they can be restored later. 

Runtime variable files, such as files holding process identifiers(PID s) and logged user 
information (utmp). Files in this directory are usually cleared when the system boots. 
Spooled (or queued) files for various programs. 

Spooled jobsfor at(l). 

Spooled jobsforcron(l). 

Spooled files for printing. 

Users' mailboxes. 

Spooled files for the smaii(l) mail delivery program. 

Spool directory for the news subsystem. 

Spooled files for uucp(l). 

Like /tmp, this directory holds temporary files stored for an unspecified duration. 


C0NF0RMST0 

The Linux filesystem standard, release 1.2. 

BUGS 

This list is not exhaustive; different systemsmay be configured differently. 

SEE ALSO 

tind(l), in(l), mount(l), proc(5), T he Linux Filesystem Standard 

Linux, 10 February 1996 


hostname 

hostname— FI ostname resolution description. 



hostname 



DESCRIPTION 

H ostnames are domains. A domain is a hierarchical, dot-separated list of subdomains For example, thernachinemonet in the 
Berkeley subdomain of theEDu subdomain of the Internet Domain N ame System is represented asmonet.Berkeiey.EDu (with 
no trailing dot). 

H ostnames are often used with network client and server programs, which must generally translate the name to an address 
for use. (This task is usually performed by the library routine gethostbyname(3).) The default method for resolving hostnames 
by the Internet name resolver is to follow RFC 1535's security recommendations. Actions can betaken by the administrator 
to override these recommendations and to have the resolver behave the same as earlier, non-RFC 1535 resolvers. 

The default method (using RFC 1535 guidelines) follows. 

If the name consists of a single component (that is, contains no dot) and if the environment variable hostaliases is set to the 
name of a file, that file is searched for a string matching the input hostname. The file should consist of lines made up of two 
strings separated by whitespace, the first of which is the hostname alias and the second of which is the complete hostname to 
be substituted for that alias. If a case-insensitive match is found between the hostname to be resolved and the first field of a 
line in the file, the substituted name is looked up with no further processing. 

If there is at least one dot in the name, then the name isfirst tried as is The number of dots to cause this action is 
configurable by setting the threshold using the ndots option in /etc/resoiv.cont (default is i ). If the name ends with a dot, 
the trailing dot is removed, and the remaining name is looked up (regardless of the setting of the ndots option) and no 
further processing is done 

If the input name does not end with a trailing dot, it is looked up by searching through a list of domains until a match is 
found. If neither the search option in the/etc/resoiv.cont file or the localdomain environment variable isused, then the 
search list of domainscontainsonly thefull domain specified by thedomain option (in /etc/resoiv.cont) orthedomain 
used in the local hostname (see hostname(l) and resoiver(5)). For example, if thedomain option is set to cs.Berkeiey.EDu, 
then onlycs.Berkeiey.EDu is in the search list and is the only domain appended to the partial hostname For example, a 
setting of lithium rnakesiithium.cs.Berkeiey.EDu the only name to be tried using the search list. 

If the search option isused in /etc/resoiv.cont or the environment variable, localdomain is set by theuser, then thesearch 
list includes what is set by these methods. For example if thesearch option contained cs.Berkeiey.EDu cchem.Berkeiey.EDu 
Berkeiey.EDu, then the partial hostname(such as lithium) istried with each domain name appended (in thesameorder 
specified). The resulting hostnames that are tried include 

lithium.CS.Berkeley.EDU 

lithium.CChem.Berkeley.EDU 

lithium.Berkeley.EDU 

The environment variable localdomain overrides the search and domain options, and if both search and domain options are 
present in the resolver configuration file then only the last one listed isused (see resoiver(5)). 

If the name was not previously tried "as is" (that is, it fell below the ndots threshold or did not contain a dot), then the name 
as originally provided is attempted. 

SEE ALSO 

gethostbyname(3), resolver(5), mailaddr(7), named(8) 

16 February 1994 


iso_8859_1 

iso_8859_i — The ISO 8859-1 character set encoded in octal, decimal, and hexadecimal. 

DESCRIPTION 

ThelSO 8859 standard includes several 8-bit extensions to theASC II character set (also known asISO 646-1RV). Especially 
important is I SO 8859-1, the Latin Alphabet N o. 1, which has become widely implemented and may already be seen as the 
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de facto standard ASCII replacement. ISO 8859-1 supports the following languages: Afrikaans, Basque, Catalan, Danish, 
Dutch, English, Faeroes, Finnish, French, Galician, German, Icelandic, Irish, Italian, Norwegian, Portuguese, Scottish, 
Spanish, and Swedish. N ote that the ISO 8859-1 characters are also the first 256 characters of ISO 10646 (Unicode). 


ISO 8859 ALPHABETS 

The full set of ISO 8859 alphabets includes 

ISO 8859-1 

ISO 8859-2 

ISO 8859-3 

ISO 8859-4 

ISO 8859-5 

ISO 8859-6 

ISO 8859-7 

ISO 8859-8 

ISO 8859-9 

ISO 8859-10 


W est European languages (Latin-1) 

East European languages (Latin-2) 

Southeast European and miscellaneous languages (Latin-3) 
Scandinavian/Baltic languages (Latin-4) 

Latin/Cyrillic 
Latin/Arabic 
Latin/Greek 
Latin/H ebrew 

Latin-1 modification forT urkish (Latin-5) 

Lappish/N ordic/Eskimo languages (Latin-6) 


ISO 8859-1 CHARACTERS 

The following table displays the characters in ISO 8859 Latin-1, which are printable and unlisted in theascii(7) manual 
page. 


Oct 

Dec 

Hex 

Char 

D ascription 

240 

160 

A0 


N o-break space 

241 

161 

A1 

i 

Inverted exclamation mark 

242 

162 

A2 

4 

Cent sign 

243 

163 

A3 

£ 

Pound sign 

244 

164 

A4 

$ 

Currency sign 

245 

165 

A5 

¥ 

Yen sign 

246 

166 

A6 

1 

1 

Broken bar 

247 

167 

A7 

§ 

Section sign 

250 

168 

A8 


D iaeresis 

251 

169 

A9 

© 

Copyri ght sign 

252 

170 

AA 

a 

Feminineordinal indicator 

253 

171 

AB 

« 

Left-pointing double angle quotation 
mark 

254 

172 

AC 

- 

N otsign 

255 

173 

AD 

- 

Soft hyphen 

256 

174 

AE 

® 

Registered sign 

257 

175 

AF 

“ 

M acron 

260 

176 

B0 

0 

Degree sign 

261 

177 

B1 

± 

Plus-minus sign 

262 

178 

B2 

2 

Superscript two 

263 

179 

B3 

3 

Superscri pt three 
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1241 


Oct 

Dec 

Hex 

Char 

D escription 

264 

180 

B4 


Acute accent 

265 

181 

B5 


M icro sign 

266 

182 

B6 

It 

Pilcrowsign 

267 

183 

B7 


M iddledot 

270 

184 

B8 

S 

Cedilla 

271 

185 

B9 

1 

Superscript one 

272 

186 

BA 

o 

M asculineordinal indicator 

273 

187 

BB 

» 

Right-pointing double angle 
quotation mark 

274 

188 

BC 

1/4 

Vulgar fraction onequarter 

275 

189 

BD 

1/2 

Vulgar fraction onehalf 

276 

190 

BE 

3/4 

Vulgar fraction three quarters 

277 

191 

BF 

L 

Inverted question mark 

300 

192 

CO 

A 

Latin capital letter A with grave 

301 

193 

Cl 

A 

Latin capital letter A with acute 

302 

194 

C2 

A 

Latin capital letter A with circumflex 

303 

195 

C3 

A 

Latin capital letter A with tilde 

304 

196 

C4 

A 

Latin capital letter A with diaeresis 

305 

197 

C5 

A 

Latin capital letter A with ring above 

306 

198 

C6 

/E 

Latin capital ligatureAE 

307 

199 

C7 

c 

Latin capital letter C with cedilla 

310 

200 

C8 

E 

Latin capital letter E with grave 

311 

201 

C9 

E 

Latin capital letter E with acute 

312 

202 

CA 

E 

Latin capital letter E with circumflex 

313 

203 

CB 

E 

Latin capital letter E with diaeresis 

314 

204 

CC 

i 

Latin capital letter 1 with grave 

315 

205 

CD 

i 

Latin capital letter 1 with acute 

316 

206 

CE 

1 

Latin capital letter 1 with circumflex 

317 

207 

CF 

1 

Latin capital letter 1 with diaeresis 

320 

208 

DO 

D 

Latin capital letter eth 

321 

209 

D1 

N 

Latin capital letter N with tilde 

322 

210 

D 2 

0 

Latin capital letter O with grave 

323 

211 

D 3 

6 

Latin capital letter O with acute 

324 

212 

D 4 

0 

Latin capital letter O with circumflex 

325 

213 

D 5 

0 

Latin capital letter O with tilde 

326 

214 

D 6 

6 

Latin capital letter O with diaeresis 

327 

215 

D 7 

X 

M ultiplication sign 

330 

216 

D 8 

0 

Latin capital letter O with stroke 

331 

217 

D 9 

0 

Latin capital letter U with grave 

332 

218 

DA 

0 

Latin capital letter U with acute 

333 

219 

DB 

u 

Latin capital letter U with circumflex 


continues 
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Oct 

Dec 

Hex 

Char 

D escription 


334 

220 

DC 

0 

Latin capital letter U with diaeresis 

335 

221 

DD 

Y 

Latin capital letter Y with acute 

336 

222 

DE 

P 

Latin capital letter thorn 

337 

223 

DF 

6 

Latin small 

letter sharp s 

340 

224 

EO 

a 

Latin small 

letter a with grave 

341 

225 

El 

a 

Latin small 

letter a with acute 

342 

226 

E2 

a 

Latin small 

letter a with circumflex 

343 

111 

E3 

a 

Latin small 

letter a with tilde 

344 

228 

E4 

a 

Latin small 

letter a with diaeresis 

345 

229 

E5 

a 

Latin small 

letter a with ring above 

346 

230 

E6 

ae 

Latin small 

ligature ae 

347 

231 

E7 

$ 

Latin small 

letter c with cedilla 

350 

232 

E8 

e 

Latin small 

letter ewith grave 

351 

233 

E9 

e 

Latin small 

letter ewith acute 

352 

234 

EA 

e 

Latin small 

letter ewith circumflex 

353 

235 

EB 

e 

Latin small 

letter ewith diaeresis 

354 

236 

EC 

i 

Latin small 

letter i with grave 

355 

237 

ED 

i 

Latin small 

letter i with acute 

356 

238 

EE 

i 

Latin small 

letter i with circumflex 

357 

239 

EF 

i' 

Latin small 

letter i with diaeresis 

360 

240 

FO 

3 

Latin small 

letter eth 

361 

241 

FI 

n 

Latin small 

letter n with tilde 

362 

242 

F2 

6 

Latin small 

letter o with grave 

363 

243 

F3 

6 

Latin small 

letter o with acute 

364 

244 

F4 

6 

Latin small 

letter o with circumflex 

365 

245 

F5 

6 

Latin small 

letter o with tilde 

366 

246 

F6 

6 

Latin small 

letter o with diaeresis 

367 

247 

F7 

+ 

D ivision sign 

370 

248 

F8 

0 

Latin small 

letter o with stroke 

371 

249 

F9 

u 

Latin small 

letter u with grave 

372 

250 

FA 

u 

Latin small 

letter u with acute 

373 

251 

FB 

u 

Latin small 

letter u with circumflex 

374 

252 

FC 

ij 

Latin small 

letter u with diaeresis 

375 

253 

FD 

y 

Latin small 

letter y with acute 

376 

254 

FE 

P 

Latin small 

letter thorn 

377 

255 

FF 

y 

Latin small 

lottery with diaeresis 


SEE ALSO 

ascii(7) 


11 July 1995 
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locale 

Locale—Description of multi-language support. 

SYNOPSIS 

#include <locale.h> 

DESCRIPTION 

A locale is a set of language and cultural rules. These cover aspects such as language for messages, different character sets, 
lexi graphic conventions, and so on. A program needs to be ableto determine its locale and act accordingly to be portable to 
different cultures. 

The header <iocaie.h> declares data types, functions and macros that are useful in this task. 

T he functions it declares are setiocaieo to set the current locale and iocaieconv() to get information about number 
formatting. 


There are different categories for local information a program might need; they are declared as macros. Using them as the 
first argument to the setiocaieo function, it is possible to set one of these to the desired locale: 


LC_COLLATE 

T his is used to change the behavior ofthefunctionsstrcoiio and strxfrmo, which 
are used to compare strings in the local alphabet. For example the German sharp sis 
sorted as"ss." 

LC_TYPE 

This changes the behavior of the character handling and classification functions, 
such asisuppero and touppero and the multi-byte character functions such as 
mblen( ) Of wctomb(). 

LC_MONETARY 

Changes the behavior of the information returned by locaieconvo, which describes 
the way numbers are usually printed, with details such as decimal point versus 
decimal comma. 

LC_MESSAGES 

C hanges the language messages are displayed in. 

LC_TIME 

Changes the behavior of the strf timed function to display the current time in a 
locally acceptable form; for example, most of Europe uses a 24-hour clock versus the 
U.S. 12-hour clock. 

LC_ALL 

All of the above. 


If the second argument to setiocaieo is empty string for the default locale it is determined using the following steps: 

1. If there is a non-null environment variable lc_all, the value of lc_all is used. 

2. If an environment variable with the same name as one of the preceding categories exists and is non-null, itsvalueisused 
for that category. 

3. If there is a non-null environment variable lang, the value of lang is used. 

Values about local numeric formatting are made availablein astruct iconv returned by theiocaieconvo function, which has 
the following declaration: 

struct Iconv 
{ 

/* Numeric (non-monetary) information. */ 

char *decimal_point; /* Decimal point character. */ 

char *thousands_sep; /* Thousands separator. */ 

/* Each element is the number of digits in each group; 
elements with higher indices are farther left. 

An element with value CHAR_MAX means that no further grouping is done. 

An element with value 0 means that the previous element is used for all 
groups farther left. */ 
char *grouping; 

/* Monetary information. */ 
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/* First three chars are a currency symbol from ISO 4217. 

Fourth char is the separator. Fifth char is 1 '. */ 
char *int_curr_symbol; 

char *currency_symbol; /* Local currency symbol. */ 
char *mon_decimal_point; /* Decimal point character. */ 
char *mon_thousands_sep; /* Thousands separator. */ 
char *mon_grouping; /* Like 'grouping' element (above). */ 
char *positive_sign; /* Sign for positive values. */ 
char *negative_sign; /* Sign for negative values. */ 
char int_frac_digits; /* Int'l fractional digits. */ 
char frac_digits; /* Local fractional digits. */ 

/* 1 if currency_symbol precedes a positive value, 0 if succeeds. */ 
char_p_cs_precedes; 

/* 1 if a space separates currency_symbol from a positive value. */ 
char_p_sep_by_space; 

/* 1 if currency_symbol precedes a negative value, 0 if succeeds. */ 
char_n_cs_precedes; 

/* 1 if a space separates currency_symbol from a negative value. */ 
char_n_sep_by_space; 

/* Positive and negative sign positions: 

0 Parentheses surround the quantity and currency_symbol. 

1 The sign string precedes the quantity and currency_symbol. 

2 The sign string succeeds the quantity and currency_symbol. 

3 The sign string immediately precedes the currency_symbol. 

4 The sign string immediately succeeds the currency_symbol. */ 
char_p_sign_posn; 

char_n_sign_posn; 

}; 


C0NF0RMST0 

POSIX.1 

At the moment, the only locales supported by Linux are the portablec, posix (identical totheC locale), iso-8859-i 
(European Latin-1), and koi-8 (Russian) locales. 

SEE ALSO 

setlocale(3), localeconf(3), locale(l), localedef(l) 

Linux, 24 April 1993 


mailaddr 

maiiaddi — M ail addressing description. 

DESCRIPTION 

M ail addresses are based on the AR PAN ET protocol listed at the end of this manual page. These addresses are in the general 
format 

user @d o ma i n 

A domai n is a hierarchical dot separated list of subdomains. For example theaddress 
eric@monet.berkeley.edu 

is usually interpreted from right to left. The message should go to the ARP A name tables (which do not correspond exactly 
to the physical ARPAN ET) and then to the Berkeley gateway, after which it should go to the local hostmonet. W hen the 
message reaches monet, it is del ivered to the user eric. 
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Unlike some other forms of addressing, this does not imply any routing. Thus, although this address is specified as an ARPA 
address, it might travel by an alternate route if that were more convenient or efficient. For example, at Berkeley, the 
associated message would probably go directly to monet over the Ethernet rather than go via the Berkeley ARPAN ET 
gateway. 

ABBREVIATION 

Under certain circumstances, it might not be necessary to type the entire domain name In general, anything following the 
first dot may be omitted if it is the same as the domain from which you are sending the message. For example a user on 
caider.berkeiey.edu could send to eric?monet withoutaddingtheberkeiey.edu because it is the same on both sending and 
receiving hosts. 

Certain other abbreviations may be permitted as special cases. For example at Berkeley, ARPAN ET hosts may be referenced 
withoutaddingtheberkeiey.edu as long as their names do not conflictwith alocal hostname. 

COMPATIBILITY 

Certain old address formats are converted to the new format to provide compatibility with the previous mail system. In 
parti cular, 

user@host .ARPA 

is allowed and 
host :user 
is converted to 

user @host 

to be consistent with the rcp(l) command. 

Also, the syntax 
host luser 
is converted to 

user ©host .UUCP 

This is usually converted back to the host tuser form before being sent on for compatibility with older UUCP hosts. 

The current implementation is not able to route messages automatically through theUUCP network. Until that time you 
must explicitly tell the mail system which hosts to send your message through to get to your final destination. 

CASE DISTINCTIONS 

Domain names (anything after the @ sign) may be given in any mixture of uppercase and lowercasewith theexception of 
UUCP hostnames. M ost hosts accept any combination of casein usernames, with the notable exception of multics sites. 

ROUTE-ADDRS 

Under some circumstances, it might be necessary to route a message through sa/eral hosts to get it to the final destination. 
Usually, this routing is done automatically, but sometimes it is desirable to route the message manually. Addresses that show 
these relays are termed "route-addrs.'' These use the syntax 

<@h o s t a, @h o s t b: u s e r @h o s t c > 

This specifies that the message should be sent to host a, from thereto host b , and finally to h os tc. This path is forced a/en if 
there is a more efficient path to host c. 

Route-addrs occur frequently on return addresses because these are generally augmented by the software at each host. It is 
generally possibleto ignore all but the u s e r @do ma i n part of the address to determinetheactual sender. 
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POSTMASTER 

Every site is required to have a user or user alias designated "postmaster" to which problems with the mail system may be 
addressed. 

OTHER NETWORKS 

Some other networks can be reached by giving the name of the network as the last component of the domain. This is not a 
standard feature and might not be supported at all sites. For example messages to CSN ET or BUN ET sites can often be 
sent to user @host .CSNET Or user@hos 1 .BITNET. 

BUGS 

The RFC 822 group syntax (group :useri ,user 2 ,user3 ;) is not supported except in the special case of group:; because of a 
conflict with old berknet-style addresses. 

Route-Address syntax is grotty. 

UUCP- and ARPAN ET-style addresses do not coexist politely. 

SEE ALSO 

maii(l), sendmaii(8); Crocker, D. H., Standard for the Format of Arpa Internet Text M essages, RFC 822. 

14 February 1989 


man 

man— M acrosto format man pages. 

SYNOPSIS 

groff -Tascii -man file ... 
groff -Tps -man file ... 
man [section] title 

DESCRIPTION 

This manual page explains the groff tmac.an macro package. This macro package should be used by developers when writing 
or porting man pages for Linux. It is fairly compatible with other versions of this macro package, so porting man pages 
should not be a major problem (exceptions include the N ET-2 BSD release, which uses a totally different macro package). 

N otethat N ET -2 BSD man pages can beused with groff simply by specifying the -mdoc option instead of the -man option. 
Usingthe -mandoc option is, however, recommended because this automatically detects which macro packageisin use. 

PREAMBLE 

Thefirst command in a man page should be 

.TH title section date source manual , 

title The title of the man page (such as man). 

secti on Thesection number the man page should be placed in (such as7). 

date The date of the last revision; remember to change this every time a change is made 

to the man page because this isthe most general way of doing version control, 
source T he sourceof the command. 

For binaries, use something such asGN U, N ET-2, SLS D istribution, M CC 
D istribution. 

For system calls, use the version of the kernel that you are currently looking at: 
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Linux 0.99.11. 

For library calls, usethesourceof thefunction: GNU, BSD 4.3, LinuxDLL 4.4.1. 
manual T he title of the manual (such as Linux Programmer's M anual). 


Themanual sections are traditionally defined as follows: 


1 Commands 

2 System calls 

3 Library calls 

4 Special files 

5 File formats and conventions 

6 Games 

7 M aero packages and conventions 

8 System management commands 

9 Kernel routines 


Those commands that can be executed by the user from within a shell. 

T hose functions that must be performed by the kernel. 

M ostof theiibc functions, such as sort(3). 

Files found in / dev. 

Theformatfor /etc/passwd and other human-readablefiles. 

A description of the standard filesystem layout, this man page, and other things. 
Commands such asmount(8), which only root can execute. 

This is a non-standard manual section and isincluded because the source code to 
the Linux kernel isfreely available under the GNU Public Licenseand many 
people are working on changes to the kernel. 


FONTS 

Although there are many arbitrary conventionsforman pages in the UN IX world, the existence of sa/eral hundred Linux- 
specific man pages defines the standards: 

For functions, the arguments are always specified using italics, even in thesYNOPsis section, where the rest of thefunction is 
specified in bold: 

int myfunction(int arge, char **argv); 

Filenames are always in italics (such as/usr/inciude/stdio.h), except in thesYNOPsis section, whereincluded files arein bold 
(such as#include <stdio.h>). 

Special macros, which are usually in uppercase, arein bold (such asMAxiNT). 

When enumerating a list of error codes, the codes are in bold (this list usually uses the .tp macro). 

Any reference to another man page(orto thesubject of the current man page) isin bold. Ifthe manual section number is 
given, it is given in roman, without any spaces (such asman(7)). 

The commands to select the typeface are given below: 


B 

Bold 

BI 

Bold alternating with italics 

BR 

Bold alternating with Roman 

I 

Italics 

IB 

Italics alternating with bold 

IR 

Italics alternating with Roman 

RB 

Roman alternating with bold 

RI 

Roman alternating with italics 

SB 

Small alternating with bold 

SM 

Small 


T raditionally, each command can have up to six arguments, but theGN U version seems to remove this limitation. 
Arguments are delimited by spaces. Double quotes can be used to specify an argument that contai ns spaces. All the 
arguments will be printed next to each other without intervening spaces, so that the. br command can be used to specify a 
word in bold followed by a mark of punctuation in Roman. 
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SECTIONS 

Sections are started with .sh followed by the heading name. If the name contains spaces and appears on thesamelineas .sh, 
then place the heading in double quotes. T raditional headings include name, synopsis, description, options, files, see also, 
diagnostics, bugs, and author. The only required heading is name, which should be followed on the next line by a one line 
description of the program: 

.SH NAME 

chess \- the game of chess 

It is extremely important that this format is followed and that there is a backslash before the single dash that follows the 
command name. This syntax is used by themakewhatis(8) program to create a database of short command descriptions for 
the whatis(l) and apropos(l) commands. 

OTHER MACROS 

Other macrosindudethefollowing: 

.dt Default tabs. 

.hp Begin hanging indent. 

.ip Begin paragraph with hanging tag. This is the same as .tp, except the tag isgiven on the 

sameline, not on thefollowing line. 

.lp Same as. pp. 

.pd Set interparagraph distance to argument. 

.pp Begin a new paragraph. 

.re End relative indent (indented paragraph). 

.rs Start relative indent (indented paragraph). 

.ss Subheading (like .sh but used for a subsection). 

.tp Begin paragraph with hanging tag. The tag isgiven on the next line. This command is 

similar to .ip. 


FILES 

/usr/local/lib/groff/tmac/tmac.an 
/usr/man/whatis 


SEE ALSO 

groff(l), man(l), whatis(l), apropos(l), makewhatis(8) 


Linux, 25July 1993 


signal 

signal— List of available signals. 

DESCRIPTION 

Linux supports the signals listed in thissection. Several signal numbers are architecture dependent. First are the signals 
described in POSIX.1: 

abort(3) aiarm(l) N ext various other signals. 

(H ere, - denotes that a signal is absent; there, where three values are given, the first one is usually valid for alpha and spare, 
the middle one for i386 and ppc, the last onefor mips Signal 29 is siginfo/sigpwr on an alpha but siglost on a spare.) 
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The letters in the Action column have the following meanings: 

A Default action isto terminatetheprocess. 

B Default action isto ignorethesignal. 

C Default action isto dump core. 

D Default action isto stop the process. 

E Signal cannot be caught. 

F Signal cannot be ignored. 

G N ot a PO SIX.1 conformant signal. 

CONFORMING TO 

POSIX.1 

BUGS 

sigio and siglost have the same value. The latter is commented out in the kernel source but the build process of some 
software still thinks that Signal 29 is siglost. 

SEE ALSO 

kill(l), kill(2), setitimer(2) 

Linux 1.3.88,14 April 1996 
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suffixes— List of file suffixes. 

DESCRIPTION 

It is customary to indicate the contents of a file with the file suffix, which consists of a period followed by one or more 
letters. M any standard utilities, such as compilers, use this to recognize the type of file they are dealing with. The make(l) 
utility is driven by rules based on file suffixes. 

Following is a list of suffixes that are likely to be found on a Linux system: 


Suffix 


FileType 


,v 

.C 

.F 

.S 

.Z 

,[0-9]+pk 

.[1-9] 

■[ l-9][a-z] 
.a 

.afm 

.arc 

arj 

.asc 


Files for RCS (Revision Control System) 
Backup file 
C++source code 

FORTRAN source with cpp(l) directives 
Assembler source with cpp(l) directives 
File compressed using compress(l) 

TeX fontfiles 

M anual page for the corresponding section 

Manual page for section plus subsection 

Static object code library 

PostScript font metrics 

ARC archive 

ARJ archive 

PGP ASCII-armored data 


continues 
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Suffix 

FileType 

.awk 

AWK language program 

.bak 

Backup file 

.bm 

Bitmap source 

.c 

C source 

.cat 

M essage catalog files 

.cc 

C++source 

.cf 

Configuration file 

.conf 

Configuration file 

.config 

Configuration file 

.cweb 

Donald Knuth'sWEB forC 

.dat 

Datafile 

.def 

M odula-2 source for definition modules 

.def 

Other definition files 

.diff 

ASCII File differences 

.doc 

Documentation file 

.dvi 

TeX device independent output 

.el 

EM ACS lisp source 

.elc 

Compiled EMACSIisp 

.eps 

Encapsulated PostScript 

,f 

FORTRAN source 

.fas 

Precompiled common lisp 

.fi 

FORTRAN includefiles 

.gif 

Graphics Interchange Format 

■gsf 

Ghostscript fonts 

■gz 

Filecompressed using gzip(l) 

.h 

C or C++header files 

.hip 

H elp file 

.htm 

HTML file imported without renaming from a brain-damaged OS 

.html 

HTML document used with the World W ideWeb 

.i 

C source after preprocessing 

.idx 

Reference or datum-index fi le for hypertext or database system 

.icon 

Bitmap source 

.image 

Bitmap source 

.in 

Configuration template, especially for GNU autoconf 

.info 

Filesforthe EM ACS info browser 

.java 

A Java source file 

■jpg 

JPEG compressed picture format 

.1 

lex(l) or flex(l) files 

.lib 

Common lisp library 

.In 

Files for use with lint(l) 

■Isp 

Common lisp source 

,m4 

M4< 1) source 

.mac 

M aero files for various programs 
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Suffix File Type 


.man 

M anual page (usually source rather than formatted) 

.me 

nroft source usi ng the me macro package 

.mf 

M etafont (font generator for T eX) source 

.mm 

Sources for grotf(l) in mm format 

.mod 

M odula-2 source for implementation modules 

.0 

Object file 

.old 

Old or backup file 

.orig 

Backup (original) version of afilefrom patch(l) 

.out 

Output file often an executable program (a.out) 

■P 

Pascal source 

.patch 

File differences from patch(l) 

■pcf 

Xll fontfiles 

.pfa 

PostScript font definition files, ASCII format 

.pfb 

PostScript font definition files, binary format 

■pgp 

PGP binary data 

.pid 

Fileto storedaemon PID (such ascrond.pid) 

■png 

Portable N etwork G raphicsfile 

■pl 

Perl script 

■pr 

Bitmap source 

■PS 

PostScript file 

.r 

RAT FOR source (obsolete) 

■rej 

Patches that patch(l) couldn't apply 

.rules 

Rulesforsomething 

.s 

Assembler source 

.sa 

Stub libraries fora.out shared libraries 

.sc 

sc( 1) spreadsheet commands 

.sh 

sh( 1) scripts 

.shar 

Archive created by theshar(l) utility 

.so 

D LL dynamic library 

.sqml 

SO M L schema or query program 

.sty 

LaTeX stylefiles 

.sym 

M odula-2 compiled definition modules 

.tar 

Archive created bythetar(l) utility 

.tar.Z 

tar archive compressed with compress(l) 

.tar.gz 

tar archivecompressed with gzip(l) 

.taz 

tar archivecompressed with compress(l) 

.tex 

TeX or LaT eX source 

.texi 

Equivalentto .texinfo 

.texinfo 

TeXinfo documentation source 

.tfm 

T eX font metrics 

■tgz 

tar archivecompressed with gzip(l) 

.tmpl 

T emplate files 


continues 
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Suffix 

FileType 

.txt 

Text file 

.uue 

Binary fileencoded with uuencode(l) 

.web 

Donald Knuth'sWEB 

■y 

yacc(l) or bison(l) (parser generator) files 

.1 

Filecompressed using pack(l) (or an old gzip(l)) 

.zoo 

ZOO archive 

~ 

EM ACS or patch backup file 

rc 

Startup (run control) file, Such as .newsrc 


CONFORMSTO 

General UNIX conventions. 

BUGS 

This list is not exhaustive. 

SEE ALSO 

file(l), make(l) 

Linux, 4 April 1996 


tr2tex 

tr2tex — C onvert a document from trotf to LaTex 

SYNOPSIS 

tr2tex [ -m ] f i I ename 

DESCRIPTION 

tr 2 tex converts a document typeset in troff to a LaTeX format. It is intended to do the first pass of the conversion. The user 
should then finish up the rest of the conversion and customize the converted manuscript to his or her liking. It can also serve 
as a tutor for those who want to convert from troff to LaTeX. 

M ost of the converted document will be in LaTeX, but some of it may be in plain TeX. It will also use some macros in 
troffms.sty or troff man. sty, which are included in the package and must be available to the document when processed with 
LaTeX. 

If thereismore than oneinput file, they will all be converted intooneLaTeX document. 

tr 2 tex understands most of the -ms and -man macrosand eqn preprocessor symbols It also understands several plain troff 
commands. Few tbi preprocessor commands are understood to help convert very simple tables. 

When converting manuals, use the -m flag. 

If a troff command cannot be converted, the line that contain that command will be commented out. 

N otethat if you have eqn symbols, you must have the inline mathematics delimiter defined by deiim in the file you are 
converting. If it is defined in another setup file, that setup file must be concatenated with the file to be converted; otherwise, 
tr 2 tex regards the inline math as ordinary text. 
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BUGS 

M any of these bugs are harmless. M ost of them cause local errors that can be fixed in the converted manuscript. 

■ Some macros and macro arguments are not recognized. 

■ Commands that are not separated from their argument by a space are not properly parsed (such as .sp3i). 

■ When some operators (notably over, sub, and sup) are renamed (via define) and then they are encountered in the text, 
tr 2 tex treats them as ordinary macros and does not apply their rules. 

■ rpiie, lpiie, and cpiie are treated thesameascpiie. 

■ rcoi and icoi are treated thesameasccoi. 

■ M ath-modesize, gsize, fat, and gfont are ignored. 

■ lineup and mark are ignored. T he rules are so different. 

■ Sometroff commands are translated to commands that require delimiters that have to be explicitly put. Because they 
are sometimes not put in troff, they can create problems. Example: .nf isnot closed by .fi. 

■ When local motions are converted to nraise or niower, an nhbox is needed, which must be put manually after the 
conversion. 

■ a sub i sub j isconverted to a_i_j , which TeX parses as a_i{j_j } with a complaint that it is vague, a sub {i sub j } is 
parsed correctly and converted to aji_j}. 

■ Line spacing isnot changed within a paragraph in TeX (which is a bad practice anyway). T eX uses the last line spacing 
in effect in that paragraph. 


TO DO 

Access registers via the .nr command. 

SEE ALSO 

texmatch(9), trmatch(9) 

AUTHOR 

Kamal Al-Yahya, Stanford University 

1 January 1987 


Unicode 

Unicode—The unified 16-bit super character set. 

DESCRIPTION 

The international standard ISO 10646 defines the Universal Character Set (UCS). UCS contains all the characters of all 
other character-set standards. It also guarantees round-trip compatibility; conversion tables can be built such that no 
information is lost when a string isconverted from any other encoding to UCS and back. 

UCS contains the characters required to represent almost all known languages. This includes apart from the many languages 
that use extensions of the Latin script also the following scripts and languages: Greek, Cyrillic, H ebrew, Arabic, Armenian, 
Gregorian,Japanese, Chinese, H iragana, Katakana, Korean, H angul, Da/angari, Bengali, Gurmukhi, Gujarati, Oriya, Tamil, 
Telugu, Kannada, M alayam.Thai, Lao, Bopomofo, and a number of others. Work is going on to include further scripts such 
asTibetan, Khmer, Runic, Ethiopian, H ieroglyphics, various Indo-European languages, and many others. For most of these 
latter scripts, it was not yet clear how they can be encoded best when thestandard was published in 1993. In addition to the 
characters required by these scripts, also a large number of graphical, typographical, mathematical, and scientific symbols 
such as those provided by TeX, PostScript, M S-DOS, M acintosh, Videotext, OCR, and many word processing systems have 
been included, as well as special codes that guarantee round-trip compatibility to all other existing character-set standards. 
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TheUCS standard (ISO 10646) describes a 31-bit character-set architecture; however, today only the first 65534 code 
positions (0x0000 to Oxfffd), which are called the Basic M ultilingual Plane (BM P), have been assigned characters, and it is 
expected that only very exotic characters (such asH ieroglyphics) for special scientific purposes will ever get a place outside 
this 16-bit BM P. 

T he U C S characters 0x0000 to 0x007f are identical to those of the classic U S-ASC11 character set and the characters in the 
range 0x0000 to OxOOff are identical to those in the I SO 8859-1 Latin-1 character set. 

COMBINING CHARACTERS 

Some code points in UCS have been assigned to combining characters. These are similar to the non-spacing accent keys on a 
typewriter. A combining character just adds an accent to the previous character. The most important accented characters 
have codes of their own in UCS; however, the combining character mechanism allows you to add accents and other 
diacritical marks to any character. The combining characters always follow the character that they modify. For example the 
German character Umlaut-A ("Latin capital letter A with diaeresis”) can either be represented by the precomposed UCScode 
0x00c4 or alternately as the combi nation of a normal "Latin capital letter A" followed by a "combining diaeresis": 0x0041 
0x0308. 

IMPLEMENTATION LEVELS 

As not all systems are expected to support advanced mechanisms such as combining characters, ISO 10646 specifies the 
following three implementation levels of UCS: 

Level 1 Combining characters and H angul Jamo characters (a special, morecomplicated encoding 

of the Korean script, where H angul syllables are coded as two or three subcharacters) are not 
supported. 

Level 2 Likelevel 1, exceptin somescripts, some combining characters are now allowed (such as 

H ebrew, Arabic, Devangari, Bengali, Gurmukhi, Gujarati, Oriya, Tamil, Telugo, Kannada, 
M alayalam, Thai, and Lao). 

Level 3 All U C S characters are supported. 

TheUnicodel.l standard published by the Unicode Consortium contains exactly theUCS Basic M ultilingual Planeat 
implementation Level 3, as described in ISO 10646. Unicodel.l also adds some semantical definitionsfor some characters 
to the definitions of I SO 10646. 

UNICODEUNDER LINUX 

Under Linux, only the BM P at implementation Level 1 should be used at the moment to keep the implementation 
complexity of combining characters low. The higher implementation levels are more suitable for special word processing 
formats but not as a generic system character set. The C typewchar_t is on Linux an unsigned 16-bit integer type and its 
values are interpreted asUCS La/el 1 BM P codes. 

The locale setting specifies whether the system character encoding is UTF-8 orlSO 8859-1, for example. Library functions 
such as wctomb, mbtowc, or wprintf can be used to transform the internal wchar_t characters and strings into the system 
character encoding and back. 

PRIVATE AREA 

In the B M P, the range OxeOOO to 0xf8ff will never be assigned any characters by the standard and is reserved for private 
usage. For the Linux community, this private area is subdivided further into the range OxeOOO to Oxefff, which can be used 
individually by any end user and the Linux zone in the range OxfOOO to 0xf8ff where extensions are coordinated among all 
Linux users. The registry of the characters assigned to the Linux zone is currently maintained by H. Peter Anvin 
(peter.Anvin@iinux.org), Yggdrasi I Computing, Inc. It contains some D EC VT100 graphics characters missing in U nicode, 
gives direct access to the characters in the console font buffer, and contains the characters used by a few advanced scripts such 
asKlingon. 
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LITERATURE 

Information technology- Universal M ultiple-0 ctet Coded Character Set (U CS). Part 1: Architecture and Basic M ultilingual 
Plane. International Standard ISO 10646-1, International Organization for Standardization, Geneva, 1993. 

This isthe official specification of UCS. Pretty official, pretty thick, and pretty expensive. For ordering information, check 
www.iso.ch. 

TheU nicode Standard— Worldwide Character Encoding Version 1.0. The Unicode Consortium, Addison-Wesley, Reading, 

M A, 1991. 

There is already Unicode 1.1.4 available The changes to the 1.0 book are avail able from ftp.unicode.org. Unicode 2.0 will 
be published again as a book in 1996. 

S. H arbison, G. Steele. C, A ReferenceM anual. Fourth edition, Prentice FI all, Englewood Cliffs, 1995, 

ISBN 0-13-326224-3. 

A good reference book about the C programming language. The fourth edition now covers also the 1994 Amendment 1 to 
thelSO C standard (I SO/I EC 9899:1990), which adds a large number of new C library functionsfor handling wide 
character sets. 

BUGS 

At the time when this man page was written, the Linux iibc support for UCS was far from complete. 

AUTHOR 

M arkllS Kuhn (mskuhn@cip.informatik.uni-erlangen.de) 

SEE ALSO 

utf-8(7) 

Linux, 27 December 1995 


UTF-8 

utf-8 — An ASCI I-compatible multi byte Unicode encoding. 

DESCRIPTION 

TheU nicode character set occupies a 16-bit code space. The most obvious Unicode encoding (known asUCS-2) consists of 
a sequence of 16-bit words. Such strings can contain as parts of many 16-bit characters bytes such as\o or /.which have a 
special meaning in filenames and other C library function parameters. In addition, the majority of U N IX tools expects 
ASCII files and can't read 16-bit words as characters without major modifications. For these reasons, UCS-2 is not a suitable 
external encoding of Unicode in filenames, text files, environment variables, and so on. ThelSO 10646 Universal Character 
Set (UCS), a superset of U nicode, occupies even a 31-bit code space, and theobviousUCS-4 encoding for it (a sequence of 
32-bit words) has the same problems 

The UTF-8 encoding of Unicode and UCS does not have these problems and is the way to go for using the U nicode 
character set under U NIX-style operating systems. 

PROPERTIES 

TheUTF-8 encoding hasthefollowing nice properties: 

UCS characters 0x00000000 to 0x0000007f (the classical U .S. ASCII characters) are encoded simply as bytes 0x00 to 0x7f 
(ASCII compatibility). This means that files and strings that contain only 7-bit ASCII characters have the same encoding 
under both ASCII and UTF-8. 

All U C S characters greater than 0x7f are encoded as a multibyte sequence consisting only of bytes in the range 0x80 to Oxfd, 
so no ASCII byte can appear as part of another character and there are no problems with \eor /. 
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T he lexicographic sorting order of U C S-4 strings is preserved. 

All possible2“31 UCS codescan be encoded using UTF-8. 

The bytes Oxfeand Oxff are never used in the UTF-8 encoding. 

T he first byte of a multi byte sequence that represents a si ngle non-ASC 11 U C S character is always in the range OxcO to Oxfd 
and indicates how long this multi byte sequence is. All further bytes in a multi byte sequence are in the range 0x80 to Oxbf. 
This allows easy resynchronization and makes the encoding stateless and robust against missing bytes. 

UTF-8-encoded UCS characters may be up to six bytes long; however, Unicode characters can only be up to three bytes 
long. Because Linux uses only the 16-bit Unicode subset of UCS, under Linux, UTF-8 multibyte sequences can only be one 
two, or three bytes long. 

ENCODING 

The following byte sequences are used to represent a character. The sequence to be used depends on theUCS code number 
of the character: 

0x00000000 - 0X0000007F: 0xxxxxxx 

0x00000080 - 0X000007FF: 110xxxxx 10xxxxxx 

0x00000800 - 0X0000FFFF: 1110x x x x 10x x x x x x 10x x x x x x 

0x00010000 - 0X001FFFFF: 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx 

0x00200000 - 0X03FFFFFF: 111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 

0x04000000 - 0X7FFFFFFF: 1111110X 1 0xxxxxx 10xxxxxx 10xxxxxx 1 0xxxxxx 

10 x x x x x x 

T he xxx-bit positions are filled with the bits of the character code number in binary representation. Only the shortest 
possi ble multi byte sequence that can represent the code number of the character can be used. 

EXAMPLES 

The Unicode character 0xa9 =1010 1001 (the copyright sign) isencoded in UTF-8 as 

11000010 10101001 = 0XC2 0xa9 

and character 0x2260 =0010 0010 0110 0000 (the"not equal" symbol) isencoded as 

11100010 10001001 10100000 = 0xe2 0x89 0xa0 

STANDARDS 

ISO 10646, Unicodel.l, XPG4, Plan 9. 

AUTHOR 

M arkus Kuhn (mskuhn@cip.informatik.uni-erlangen.de) 

SEE ALSO 

unicode(7) 
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intro 

intro— Introduction to administration and privileged commands. 

DESCRIPTION 

This chapter describes commands that either can be or are only used by the superuser, such as daemons and machine or 
hardware-related commands. 

AUTHORS 

Look at the header of the manual page for the authors and copyright conditions. Note that these can be different from page 
to page. 

Linux, 24July 1993 


adduser,addgroup 

adduser, addgroup— Add a user or group to the system. 

SYNOPSIS 

adduser [--system [--home directory] [--group]] [--quiet] 

[--force-badname] [--help] [--version] [--debug] username 
adduser [--quiet] [--force-badname] [--help] [--version] 

[ - -debug ] user name group 

adduser [--group] [--quiet] [--force-badname] [--help] 

[--version] [--debug] group 

DESCRIPTION 

adduser and addgroup add users and groups to the system according to information provided in the configuration file /etc/ 
adduser.cont. adduser and addgroup automatically determi ne the UID orGID and place the entity in the password or 
group file as appropriate. 

If necessary, adduser creates a home directory for the new user, copies "skeletal" user files to it from /e tc/skei, and allows 
the system administrator to set an initial password and finger information for the user. 

Because it needs to be able to write to such files as/ etc/passwd, adduser can only be run as root. 

Generally, there are two types of users and groups on a system: those users that log into the system and those "non-user" 
accounts and groups that exist for various system tasks and projects. H enceforth, user will refer to the login type and system 
user or group will refer to the type used for system maintenance and projects. 

By default, each user in Debian GN U/Linux is given a corresponding group with the same name and ID, allowing people 
easily to give access to their home directories to others. This option can be turned off in the configuration file, in which case 
each user is, by default, added to a group called users. 

Under Debian GN U/Linux, ID s less than or equal to 100 are allocated by the base system maintainer for various purposes. 

ID sfrom 101 to the value specified in the configuration file ( 1000 , by default) are used for system users and groups IDs 
greater than 1000 are reserved for users and their corresponding groups. 

When invoked with a single name adduser creates a user with that name. W hen given two names, adduser assumes that the 
first name represents an existing user and that the second name represents an existing group. In this case, the user is added to 
the group. 
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system 

C reate a system user. Thisuserwill be assigned the shell /bin/taise and have an 
asterisk in the password field. Unless otherwise specified, the user will be placed 
in the group nogroup. Skeletal configuration files will not be copied into the 
user's home directory. 

home di rectory 

When used with - -system, this uses di rectory as the user's home directory, 
rather than the default specified in the configuration file If the directory does 
not exist, it iscreated. 

group 

When combined with -system, a group with the same name and ID asthe 
system user iscreated. If not combined with --system, a group with thegiven 
name is created. T his isthe default action if the program is invoked as addgroup. 

quiet 

Suppress progress messages. 

force-badname 

By default, user and group names are required to consist of a lowercase letter 
followed by one or more lowercase letters or numbers. T hisoption forces 
adduser or addgroup to be more lenient. 

help 

Display brief instructions 

version 

D isplay version and copyright information. 

debug 

D isplay a large quantity of debugging information. 


SEE ALSO 

adduser.conf(5) 

COPYRIGHT 

Copyright(c) 1995, T ed H ajek, with a great deal borrowed from the original Debian adduser, copyright(c) 1994, Ian 
M urdock. adduser is free software; see the GN U General Public Li cense version two or later for copying conditions. There is 
no warranty. 

Debian GNU/Linux version 1.94 


agetty 

agetty— Alternative Linux getty. 

SYNOPSIS 

agetty [ -ihL] [-1 loginprogram] [-m] [-t timeout] port baudrate,... [term] 
agetty [ - ihL] [-1 loginprogram] [-m] [-ttimeout] baudrate,... port [term] 

DESCRIPTION 

agetty opens a tty port, prompts for a login name and invokes the /bin/iogm command. It is usually invoked by init(8). 

agetty has several non-standard features that are useful for hard-wired and for dial-in lines: 

Adapts thetty settings to parity bits and to erase, kill, end-of-line, and uppercase characters when it readsa login name. 
The program can handle 7-bit characters with even, odd, none, or space parity and 8-bit characters with no parity. The 
following special characters are recognized: @ and Control -HI (kill); #, D el and Backspace (erase); carriage return and line 
feed (end of line). 

Optionally deduces the baud rate from the connect messages produced by H ayes-compatible modems. 

Optionally does not hangup when it is given an already opened line (useful for call-back applications). 

0 ptionally does not display the contents of the /etc/issue fi le (System V only). 



Part VIII: Administration and Privileged Commands 



Optionally invokes a non-standard login program instead of /bin/login. 

Optionally turns on hardware flow control. 

Optionally forces the line to be local with no need for carrier detect. 

This program does not use the /etc/gettydets (System V) or /etc/gettytab (SunOS 4) files. 


ARGUMENTS 

port 


baud rate,... 


term 


A path name relative to the /dev directory. If a - is specified, agetty 
assumes that its standard input is already connected to a tty port and that 
a connection to a remote user has already been established. U nder System 
V, a - port argument should be preceded by a -. 

A comma-separated list of one or more baud rates. Each time agetty 
receives a break character, it advances through the list, which istreated as 
if itwere circular. Baud rates should be specified in descending order, so 
thatthenull character (C trl +@) can also beused for baud rate switching. 
Thevalueto beused fortheTERM environment variable. This overrides 
whatever init(8) may have set and is inherited by login and the shel I. 


OPTIONS 

-h 


-1 I ogi n_program 


-1 t i me o u t 

-L 


Enable hardware (RTS/CTS) flow control. It is left up to the application 
to disable software (XON/XOFF) flow protocol where appropriate. 

Do not display the contents of /etc/issue before writing the login 
prompt. Terminals or communications hardware might become confused 
when receiving lots of text at thewrong baud rate; dial-up scripts might 
fail if the login prompt ispreceded by too much text. 

Invoke the specified login program instead of /bin/iogm. This allows 
the use of a non-standard login program (for example, one that asks for a 
dial-up password or that uses a different password file). 

T ry to extract the baud rate the connect status message produced by some 
H ayes-compatible modems. T hese status messages are of the form: 
■<juni<><speed><j unk>“. agetty assumes that the modem emits its 
status message at the same speed as specified with (thefirst) baud rate 
valueon thecommand line. 

Because the -m feature might fail on heavily loaded systems, you still 
should enable break processing by enumerating all expected baud rates on 
thecommand line. 

T erminateif no username could be read within ti me out seconds. This 
option should probably not beused with hard-wired lines. 

Force the line to be a local line with no need for carrier detect. This can 
be useful when you have a locally attached terminal where the serial line 
does not set the carrier detect signal. 


EXAMPLES 

This section shows sample entries for the / etc /imttab file. 
For a hard-wired line: 

tty1:con80x60:/sbin/agetty 9600 ttyl 

For a dial-in linewith a 9600/2400/1200 baud modem: 

ttySI:dumb:/sbin/agetty -mt60 ttySI 9600,2400,1200 



These examples assume you usethesimpieinit(8) init program for Linux. If you use a SysV-likeinit (does /etc/inittab 
mention "respawn"?), refer to the appropriate manual page. 


ISSUE ESCAPES 


The/etc/issuefilemight contain certain escape codes to display the system name, date and time, and so on. All escape 
codes consist of a backslash (\) immediately followed by one of the following letters: 


b 

d 

s 

1 

m 

n 

o 

r 

t 

u 

U 

v 


I nsert the baudrate of the current line. 

Insert the current date. 

I nsert the system name, the name of the operating system. 

I nsert the name of the current tty li ne 
I nsert the architecture identifier of the machine, such as i486. 

Insert thenodenameofthemachine also known as the hostname. 

I nsert the domain name of the machi ne. 

Insert the release number of the OS, such as 1.1.9. 

Insert the current time. 

I nsert the number of current users logged in. 

I nsert the string i userorn users wheren isthenumberof current users logged in. 
I nsert the version oftheOS, such as the build date and so on. 


For example, on my system, the following /etc/issue file 

This is \n.\o (\s\m\r) \t 

displays as 

This is thingol.orcan.dk (Linux i386 1.1.9) 18:29:30 


FILES 

/var/run/utmp, the system status file 

/etc/issue, printed before the login prompt (System V only) 

/dev/consoie, problem reports (if sysiog(3) is not used) 

/etc/inittab (Linux simpieinit(8) configuration file) 

BUGS 

The baud-rate detection feature (the -m option) requires that agetty be scheduled soon enough after completion of a dial-in 
call (within 30ms with modems that talk at 2400 baud). For robustness, always use the -m option in combination with a 
multiple baud rate command-line argument so that break processing is enabled. 

The text in the/etc/issue file and the login prompt are always output with 7-bit characters and space parity. 

T he baud-rate detection feature(the -m option) requires that the modem emits its status message after raising theDCD line. 

DIAGNOSTICS 

Depending on how the program was configured, all diagnostics are written to the console device or reported via the 
sysiog(3) facility. Error messages are produced if the port argument does not specify a terminal device, if there is no utmp 
entry for the current process (System V only), and so on. 

AUTHORS 

W.Z. V enema (wietse@wzv.win.tue.m) Eindhoven University of Technology, Department of M athematicsand Computer 
Science Den Dolech 2, P.O. Box513, 5600 M B Eindhoven, TheNetherlands. 

Peter 0 rbaek (poe@daimi.aau .dk), Linux port. 
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CREATION DATE 

Sat Nov 25 22:51:05 MET 1989 

LAST MODIFICATION 

91/09/01 23:22:00 

VERSION/RELEASE 

1.29 

archive 

archive— U senet article archiver. 

SYNOPSIS 

archive [ -a archive ][-f ][-i index ][-m ][-r ] [ i n put ] 

DESCRIPTION 

archive makes copies of fi les specified on its standard input. It is usually run either as a channel feed under innd(8) or by a 
script before expire(8) is run. 

archive reads the named input file or standard input if no file is given. The input is taken as a set of lines. Blank lines and 
lines starting with a number sign (#) are ignored. All other lines should specify the name of a file to archive. If a filename is 
notan absolute pathname itistaken to be relative to /news/spool. 

Files are copied to a directory within the arc hive directory, /news/spool/news, archive. The default is to create a hierarchy 
that mimics the input files; intermediate directories are created as needed. For example the input file comp / sources/unix/ 
2211 (article 2211 in the newsgroup comp. sources, unix) is copied to /news /spool/news .archive /comp/sources /Unix/ 
2211 . If the-f flag is used, then all directory names are flattened out, replacing the slashes with periods. In this case, the file 

is Copied to /news/spool/news.archive/comp.sources.unix/ 2211. 

If the -i flag is used, then archive appends one line to the specified index file for each articlethat it copies. This line 
contains the destination name and theM essage-ID and Subject headers. 

For example, atypical newsfeeds(5) entry to archive most source newsgroups is as follows: 

source-archive\ 

: !*,*sources*,!*wanted*,!*.d\ 

:Tc,Wn\ 

:/archive -f -i \ 

/usr/spool/news/news.archive/INDEX 

Files are copied by making a link. If that fails, a new file is created. If the -m flag is used, then the file is copied to the 
destination, and the input file is replaced with a symbolic link pointing to the new file. The -m flag is ignored. 

By default, archive sets its standard error to / var / log/news/erriog.T o suppress this redirection, use the -r flag. 

If the input is exhausted, archive exits with a zero status. If an I/O error occurs, it tries to spool its input, copying it to a file. 
If there was no input filename, the standard input is copied to / news/spool/out. going/archive and the program exits. If 
an input filename was given, a temporary file named input, bch (if input is an absolute pathname) or / news/spool/ 
out.going/input.bch (if the filename does not begin with a si ash) iscreated. Oncetheinput iscopied, archive tries to 
rename this temporary file to bethenameof theinput fileand then exits. 

HISTORY 

W ritten by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 




arp 


SEE ALSO 

newsfeeds(5) 



arp 

arp— M anipulate the system ARP cache. 

SYNOPSIS 

arp [-v] [-t type] -a [hostname] 
arp [-v] -d host name ... 
arp [-v] [-t type] -s hostname hw_addr 
arp [ -v] -f f i I ename 


DESCRIPTION 

arp manipulates the kernel's ARP cache in various ways. The primary options are cl earing an address mapping entry and 
manually setting up one. For debugging purposes, the arp program also allows a complete dump of the ARP cache 


OPTIONS 

-V 

-t type 


- a [ h o s t n a me ] 

- d h o s t n a me 


-s host name hw addr 


- f f i I e n a me 


Tell theuserwhatisgoingon by being verbose. 

When setting or reading the ARP cache thisoptional parameter tells arp which class 
of entries it should check for. The default value of this parameter is ether (hardware 
code 0x01 for IEEE 802.3 10M bps Ethernet). Other values might include network 
technologies such as ARC net (arcnet), PRO net (pronet), and AX.25 (ax 2 s). 

Shows the entries of the specified hosts. If th e h o s t n a me parameter is not used, all 
entries are displayed. 

Remove the entries of the specified host. Thiscan be used if the indicated host is 
brought down, for example 

Manually create an ARP address mapping entry for host host name with hardware 
address set to hw_addr . T he format of the hardware address is dependent on the 
hardware class, but for most classes, you can assumethat the usual presentation can 
be used. For the Ethernet class, this issix bytes in hexadecimal, separated by colons 
Similar to the -s option, only this time the address info is taken from filef i i ename. 
Thiscan be used if ARP entries for a lot of hosts have to beset up. The name of the 
data file is often /etc/ethers, butthisisnot official. 

T he format of thefile is simple; it only containsASCII text lines with ahostname 
and a hardware address separated by whitespace. 


In all places where a hostname is expected, you can also enter an IP address in dotted-decimal notation. 


FILES 


/proc/net/arp 

/etc/ethers 

AUTHOR 

Fred N . van Kempen (waltje@uwalt.nl.mugnet.org) 
09 June 1994 
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badblocks 

badbiocks — Search a device for bad blocks. 

SYNOPSIS 

badblocks [ -b block-size ] [ -o output_fiI e ] [ -v ][-w ] device bl ocks-count 


DESCRIPTION 

badblocks is used to search for bad blocks on a device (usually a disk partition), device is the special file corresponding to the 
device (such as/dev/hdxx). biocks-count isthe number of blocks on the device. 


OPTIONS 

-b bl ock- si ze 
-o output file 

-v 

-w 


Specify thesize of blocks in bytes. 

Write the list of bad blocks to the specified file. Without this option, badblocks 
displaysthelist on its standard output. 

V erbose mode. 

Use write-mode test. With this option, badblocks scans for bad blocks by writing 
some patterns (Oxaa, 0x55, Oxff, and 0x00) on every block of the device, reading 
every block and comparing the contents 


WARNING 

N ever use the -w option on a device containing an existing filesystem. This option erases data! 


AUTHOR 

badblocks was written by Remy Card (car-d@masi.ibp.tr), the developer and maintainer of theext2 ts. 


BUGS 

I had no chance to make real tests of this program because I use ID E drives, which remap bad blocks I only made some tests 
on floppies. 


AVAILABILITY 

badblocks is avai lable for anonymous FT P from f tp. ibp. f r and tsx - 11 .mit. edu in /pub/linux/packages/ext 2 f s. 

SEE ALSO 

e2fsck(8), mke2fs(8) 

Version 0.5b, N ovember 1994 


buffchan 

buff chan— Buffered file-writing back end for InterN etN ews 

SYNOPSIS 

buffchan [ -b ][-c lines ][-C seconds ][-d directory ] 

[ - f fields ][-mmap ] [ - p p i d f i I e ] [ -1 lines ][-L seconds ] 

[-r ][-s fi I e format ][-u ] 

DESCRIPTION 

buffchan reads li nes from standard input and copies certain fields in each line into files named by other fields within the 
line, buffchan is intended to be called by innd(8) as an exploder feed. 



cfdisk 



buff chan input is interpreted as a set of lines. Each line contains a fixed number of initial fields, followed by a variable 
number of filename fields. All fields in a line are separated by whitespace. The default number of initial fields is one; the-f 
flag may be used to specify a different number of fields. See f iiechan(8) for an example. 

After the initial fields, each remaining field names a file to write The -s flag may be used to specify a format string that maps 
the field to a filename. This is a sprintf(3) format string, which should haveasingle%s parameter that is given the field. 

The default value is /news/spool /out. going/%s. See the description of this flag in tiiechan(8).The-dflag may be used to 
specify a directory the program should change to before starting. If this flag is used, then the default for the-s flag is 
changed to be a simple %s. 

Once buff cnan opens a file, it keeps it open. The input must therefore never specify more files than the number of available 
descriptors can keep open. If the-b flag is used, the program will allocate a buffer and attach it to thefile using setbuf(3). If 
the-u flag is used, the program will request unbuffered output. 

If the -l flag is used with a number n, then buff chan will call ffiusn(3) after every n lines are written to a file. If the -c flag 
is used with a number n, then buff chan will close, and reopen, a file after every n lines are written to a file. 

If the -l flag is used with a number n, then all files will be flushed every n seconds. Similarly, the-c flag may be used to 
specify that all files should be closed and reopened every n seconds. 

By default, the program sets its standard error to /var/iog/news/erriog. T o suppress this redirection, use the -r flag. 

If the-p flag is used, the program will write a line containing its process ID (in text) to the specified file. 

buff chan can be invoked as an exploder feed (seenewsfeeds(5)). As such, if a line starts with an exclamation point, it is 
treated as a command. T here are three commands: 

flush Thefiush command closes and reopens all open files; flush **x flushes only the 

specified site. These are analogous to thectimnd(8) flush command and can be 
achieved by doing a send flush xxx command. Applications can tell that the flush 
has completed by renaming the file before issuing the command; buff chan has 
completed the command when the original filename reappears, 
buff chan also changes the access permissions of thefile from read-only for everyone 
to read-write for owner and group as it flushes or closes each output file. It changes 
the modes back to read-only if it reopens the same file. 

drop The drop command is similar to thefiush command except that any files are not 

reopened. If given an argument, then the specified site is dropped; otherwise, all sites 
are dropped. (Note that the site will be restarted iftheinput stream mentionsthe 
site.) When a ctimnd "drop site” command is sent, innd will automatically forward 
the command to buff chan if thesiteisafunnel that feeds into this exploder. T o 
drop all sites, use the ctiinnd send buf fchan - site drop command, 
readmap The map file (specified with the-m flag) is reloaded. 

HISTORY 

W ritten by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

ctlinnd(8), filechan(8), innd(8), newsfeeds(5). 

cfdisk 

cfdisk—Curses-based disk partition table manipulator for Linux. 

SYNOPSIS 


cfdisk [ -avz ] [ -c cylinders ][-h heads ][-s sectors-per•track ][-P opt ] 
[devi ce ] 
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DESCRIPTION 

cf disk is a curses-based program for partitioning a hard disk drive. The device can beany one of the following: 

/dev/hda [default] 

/dev/hdb 

/dev/sda 

/dev/sdb 

/dev/sdc 

/dev/sdd 

cfdisk first triesto read the geometry of the hard disk. If it fails, an error message is displayed and cfdisk exits. Thisshould 
only happen when partitioning a SC SI drive on an adapter without a BIOS. T o correct this problem, you can set the 
cylinders, heads, and sectors-per-track on thecommand line. N ext, cfdisk triesto read the current partition tablefrom the 
disk drive. If it is unable to figure out the partition table, an error is displayed and the program exits. This might also be 
caused by incorrect geometry information and can be overridden on thecommand line. Another way around thisproblem is 
with the -z option. Thiswill ignore the partition tableon thedisk. 

The main display is composed of four sections, from top to bottom: the header, the partitions, thecommand line, and a 
warning line. The header contains the program name and version number followed by thedisk drive and its geometry. The 
partitions section always displays the current partition table. Thecommand line is the place where commands and text are 
entered. The available commands are usually displayed in brackets. The warning line is usually empty except when there is 
important information to be displayed. The current partition is highlighted with ra/erse video (or an arrow if the - a option 
is given). All partition-specific commands apply to the current partition. 

The format of the partition table in the partition's section is, from left to right: N ame, Flags, Partition Type, Filesystem 
Type, and Size. The name is the partition device name. The flags can be Boot, which designates a bootable partition or N C, 
which stands for "N ot Compatible with DOS or OS/2." DOS, OS/2, and possibly other operating systems require the first 
sector of the first partition on thedisk and all logical partitions to begin on the second head. This wastes the second through 
the last sector of the first track of the first head (the first sector is taken by the partition table itself), cfdisk allows you to 
recover these "lost" sectors with the maximize command (m). N otethat fdisk(8) and some early versions of DOS create all 
partitions with the number of sectors already maximized. For more information, see the maximize command later in this 
chapter. The partition type can be Primary or Logical. For unallocated space on the drive, the partition type can also be 
Pri/Log or empty (if the space is unusable). The filesystem type section di splays the name of the filesystem used on the 
partition, if known. If it is unknown, then Unknown and the hex value of the filesystem type are displayed. A special case 
occurs when there are sections of thedisk drive that cannot be used (because all the primary partitions are used). When this 
is detected, thefilesystem typeisdisplayed as unusable. Thesize field displays the size of the partition in megabytes(by 
default). It can also display the size in sectors and cylinders (see the change units command later in this chapter). If an 
asterisks (*) appears after thesize, this means that the partition is not aligned on cylinder boundaries. 

DOS WARNING 

TheDOS 6.x format command looks for some information in the first sector of the data area of the partition and treats this 
information as more reliable than the information in the partition table, dos format expects dos fdisk to clear the first 512 
bytes of the data area of a partition whenever a size change occurs dos format looks at this extra information even if the / u 
flag is given; we consider this a bug in dos format and dos fdisk. 

The bottom line is that if you use cfdisk or fdisk to change the size of a DOS partition table entry and then you must also 
usedd to zero the first 512 bytes of that partition before using dos format to format the partition. For example if you were 
using cfdisk to make a DOS partition table entry for /dev/hdai, then (after exiting fdisk or cfdisk and rebooting Linux 
so that the partition table information isvalid), you usethecommand dd if=/dev/zero of=/dev/hdai bs=5i2 count=i to 
zero thefirst 512 bytes of the partition. 

Be extremely careful if you use the dd command because a small typo can make all of the data on your disk useless. 

For best results you should always use an OS-specific partition tableprogram. For example, you should makeDOS 
partitions with the dos fdisk program and Linux partitions with the Linux fdisk or Linux cfdisk program. 



cfdisk 



COMMANDS 

cfdisk commands can be entered by pressing the desired key (pressing Enter after the command is not necessary). H ere is a 

list of the available commands: 

b T oggle bootable flag of the current partition. This allows you to select which primary partition is 

bootable on the drive. 

d Delete the current partition. Thiswill convert the current partition into free space and mergeit 

with any free space immediately surrounding thecurrent partition. A partition already marked as 
free space or marked as unusable cannot be deleted. 

g Change the disk geometry (cylinders, heads, or sectors-per-track). Warning: This option should 

only be used by people who know what they are doing. A command-line option is also available to 
change the disk geometry. While at the change disk geometry command line, you can choose to 
change cylinders (d), heads (h), and sectors per track (s). The default value will be printed at the 
prompt, which you can accept by simply pressing the Enter key or you can exitwithout changes by 
pressing the Esc key. If you want to change the default value simply enter the desired value and 
press Enter. The altered disk parameter values do not take effect until you return to the main menu 
(by pressing Enter or Esc at the change disk geometry command line. If you change the geometry 
such that the disk appears larger, the extra sectors are added at the end of the disk as free space. If 
the disk appears smaller, thepartitionsthat are beyond the new last sector are deleted and the last 
partition on the drive (or the free space at the end of thedrive) ismadeto end atthenew last 
sector. 

h Print the help screen. 

m M aximize disk usage of thecurrent partition. This command will recover the the unused space 

between the partition table and the beginning of the partition, at the cost of making the partition 
incompatiblewith DOS, OS/2, and possibly other operating systems. Thisoption will toggle 
between maximal disk usage and DOS, OS/2, and so on compatible disk usage. The default when 
creating a partition isto createDOS, OS/2, and so on compatible partitions. 

n Create new partitionsfrom free space. If the partition type is Primary or Logical, a partition of 

that type will be created, but if the partition type is pri/Log, you will be prompted forthetypeyou 
want to create. Be aware that there are only four slots available for primary partitions and because 
there can be only one extended partition that contains all ofthe logical drives, all of thelogical 
drives must be contiguous (with no intervening primary partition), cfdisk next prompts you for 
the size of the partition you want to create. The default size, equal to the enti re free space of the 
current partition, is displayed in megabytes. You can either press the Enter key to accept the default 
size or enter a different size at the prompt, cfdisk accepts size entries in megabytes (m) (default), 
kilobytes (k), cylinders (d), and sectors (s) when you enter the number immediately followed byM, 
k, c, or s. If the partition fills the free space available the partition is created and you are returned 
to the main command line. Otherwise, the partition can be created at the beginning or theend of 
the free space, and cfdisk will ask you to choose where to place the partition. After the partition is 
created, cfdisk automatically adjusts the other partition's partition types if all oftheprimary 
partitions are used. 

p Print the partition table to the screen or to a file. There are several different formats for the 

partition that you can choose from: 

r Raw data format (exactly what would be written to disk). 

s Partition table in sector order format. 

t Partition table in raw format. T he raw data format will print the sectors that would be written to 

disk if awrite command isselected. First, the primary partition table is printed, followed by the 
partition tables associated with each logical partition. The data is printed in hex byte-by-byte with 
16 bytes per line The partition table in sector order format will print the partition table ordered by 
sector number. The fields, from left to right, are the number of the partition, the partition type, the 
first sector, the last sector, the offset from the first sector of the partition to the start of the data, the 
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length of the partition, thefilesystem type (with thehexvaluein parentheses), and the flags (with 
the hex value in parentheses). In addition to the primary and logical partitions, free and unusable 
space is printed and the extended partition is printed before the first logical partition. 

If a partition does not start or end on a cylinder boundary or if the partition length is not divisible 
by thecylinder size, an asterisk (*) isprinted after the non-aligned sector number/count. This 
usually indicates that a partition was created by an operating system that either does not align 
partitions to cylinder boundaries or that used different disk geometry information. If you know the 
disk geometry of the other operating system, you can enter the geometry information with the 
change geometry command (g). 

For thefirst partition on the disk and for all logical partitions, if the offset from the beginning of 
the partition is not equal to the number of sectors per track (that is, the data does not start on the 
first head), a number sign (#) isprinted after the offset. For the remaining partitions, if the offset is 
not zero, a number sign isprinted after the offset. This corresponds to the nc flag in the partitions 
section of the main display. 

The partition table in raw format will print the partition table ordered by partition number. It will 
leave out all free and unusable space. The fields, from left to right, are the number of the partition, 
theflags (in hex), thestarting head, sector, and cylinder, thefilesystem ID (in hex), the ending 
head, sector, and cylinder, thestarting sector in the partition, and the number of sectors in the 
partition. The information in thistablecan be directly translated to theraw data format. The 
partition table entries only have 10 bits avail able to represent thestarting and ending cylinders. 
Thus, when the absolute starting (ending) sector number is on a cylinder greater than 1023, the 
maximal values for starting (ending) head, sector, and cylinder are printed. This is the method used 
by OS/2, and it fixes the problems associated with OS/2'stdisk rewriting the partition table when 
it is not in this format. Because Linux and OS/2 use absolute sector counts, the values in the 
starting and ending head, sector, and cylinder are not used, 
q Quit program. This will exit the program without writing any data to disk, 

t Change the filesystem type. By default, new partitions are created as Linux partitions, but because 

cf disk can create partitionsfor other operating systems, changing the partition type allows you to 
enter the hex value of thefilesystem you desire. A list of the known filesystem types is displayed. 
You can type the filesystem type at the prompt or accept the default filesystem type (Linux), 
u C hange units of the partition size display. It will rotate through megabytes, sectors, and cylinders, 

w W rite partition table to disk (you must enter an uppercase w). Because this might destroy data on 

the disk, you must either confirm or deny the write by entering yes or no. If you enter yes, ctdisk 
will write the partition tableto disk and thetell the kernel to re-read the partition tablefrom the 
disk. The re-reading of the partition tableworksin most cases, butl have seen it fail. Don't panic. 

It will be correct after you reboot the system. In all cases, I still recommend rebooting the system 
just to be safe. 

Up arrow, Down arrow M ove cursor to the previous or next partition. If there are more partitionsthan can be displayed on 
a screen, you can display the next (previous) set of partitions by moving down (up) at the last (first) 
partition displayed on thescreen. 

Ctrl+L Redraws the screen. In case something goes wrong and you cannot read anything, you can refresh 

thescreen from the main command line. 

? Print the help screen. 

All the commands can be entered with either uppercase or lowercase letters (except for writes). When in a submenu or at a 
prompt to enter a filename, you can hit the Esc key to return to the main command line. 

OPTIONS 

-a 

-V 



Use an arrow cursor instead of reverse video for highlighting the current partition. 
Print the version number and copyright. 
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-c cylinders 
-h heads 

-s sectors-per-1 rack 


-P opt 


Start with zeroed partition table. This option is useful when you want to repartition 
your entire disk. N ote that this option does not zero the partition table on the disk; 
rather, it simply starts the program without reading the existing partition table. 


Override the number of cylinders, heads, and sectors-per-track read from the BIOS. If 
your BIOS or adapter does not supply this information or if it supplies incorrect 
information, use these options to set the disk geometry values. 

Prints thepartition tablein specified formats, opt can be one or more of r, s, ort.See 
the print command for more information on the print formats. 


SEE ALSO 

fdisk(8) 

BUGS 

The current version does not support multiple disks (future addition). 

AUTHOR 

Kevin E. M artin (martin@cs.unc.edu) 

TheBOGUS Linux Release, 3Junel995 


chat 

chat— Automated conversational script with a modem. 

SYNOPSIS 

chat [ options ] scri pt 


DESCRIPTION 

The chat program defines a conversational exchange between the computer and the modem. Its primary purpose is to 
establish the connection between the Point-to-Point protocol daemon (pppd) and the remote's pppd process. 


OPTIONS 

-f <c hat fi I e > 


-1 <t i me o u t > 


-r <report f i I e > 


Read the chat script from the chat file. T he use of this option is mutually exclusive with 
the chat script parameters. The user must have read access to the file. M ultiple lines are 
permitted in thefile Space or horizontal tab characters should beused to separate the 
strings. 

Set the time-out for the expected string to be received. If the string isnot received 
within thetimelimit, then the reply string isnotsent. An alternate reply may be sent or 
the script will fail ifthereisno alternate reply string. A failed script will cause thechat 
program to terminate with a nonzero error code. 

Set the filefor output of the report strings. Ifyou use the keyword report, the resulting 
strings are written to thisfile. If this option isnot used and you still use report 
keywords the stderr file isused for the report strings. 

Request that thechat script be executed in a verbose mode. The chat program will then 
log all text received fromthemodem and theoutputstringsthatitsendstothesYSLOG. 
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-v Request that the chat script be executed in a stderr verbose mode. The chat program 

will then log all text received from the modem and the output strings that it sends to the 
stderr devi ce. T his devi ce is usually the local console at the station runni ng the chat or 
pppd program. This option does not work properly if the stderr is redirected to the / 
dev/nuii location becausein that casepppd should run in the detached mode. In that 
case, use the -v option to record the session on thesvsLOG device, 
script If the script is not specified in a file with the -f option, then the script is included as 

parametersto the chat program. 


CHAT SCRIPT 

The chat script defines the communications. 

A script consists of one or more"expect-send'' pairs of strings, separated by spaces, with an optional "subexpect-subsend” 
string pair, separated by a dash as in thefollowing example: 

ogin:-BREAK-ogin: ppp ssword: hello2u2 

This line indicates that the chat program should expect the string ogin:. If it fails to receive a login prompt within the time 
interval allotted, it is to send a break sequence to the remote and then expect the string ogin:. If the first ogin: is received, 
then the break sequence is not generated. 

Once it receives the login prompt, the chat program will send the string ppp and then expect the prompt ssword:. When it 
receives the prompt for the password, it will send the password neiio 2 u 2 . 

A carriage return is usually sent following the reply string. It is not expected in the "expect” string unless it is specifically 
requested by using the nr character sequence. 

Theexpect sequence should contain only what is needed to identify the string. Because it is usually stored on a disk file it 
should not contain variable information. It is generally not acceptable to look for time strings, network identification strings, 
or other variable pieces of data such as an expect string. 

To help correct for characters that may be corrupted during the initial sequence; look for the string ogin: rather than 
login:. It is possible that the leading 1 character might be received in error and you might never find the string even though 
it was sent by the system. For this reason, scripts look for ogin: rather than login: and ssword: rather than password:. 

A very simple script might look like this 

ogin: ppp ssword: hello2u2 

In other words, expect_ ogin:, send ppp, expect.. .ssword:, send neiio 2 u 2 . 

In actual practice, simple scripts are rare. At the vary least, you should include subexpect sequences in case the original string 
is not received. For example, consider thefollowing script: 

ogin:-ogin: ppp ssword: hello2u2 

Thisisa better script than the simple one used earlier. T his looksfor the same login: prompt; however, if onewasnot 
received, a single return sequence is sent and then it will look for login: again. Should line noise obscure the first login 
prompt then sending the empty line will usually generate a login prompt again. 


ABORT STRINGS 

M any modems will report the status of the cal I as a string. These strings may be connected or no carrier or busy. It is 
often desirable to term in ate the script if the modem fails to connect to the remote. The difficulty is that a script does not 
know exactlywhich modem string it might receive. On oneattempt, it might receiveBusY, but the next time, it might 
receive no carrier. 

These "abort” strings can be specified in the script using the abort sequence. It is written in the script as in thefollowing 
example: 


ABORT BUSY ABORT 'NO CARRIER 1 ■ ATZ OK ATDT5551212 CONNECT 
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This sequence will expect nothing and then send the string AT Z. The expected response to this is the string ok. W hen it 
receives ok, the string ATDT 5551212 dials the telephone. The expected string is connect. If thestring connect is received, the 
remainder of the script is executed. H owever, if the modem finds a busy telephone, it sends the string busy. This causes the 
string to match the abort character sequence. The script then fails because it found a match to the abort string. If it received 
thestring no carrier, it aborts for the same reason. Either string may be received. Either string will terminate thechat 
script. 

REPORT STRINGS 

A report string is similar to the abort string. The difference isthat the strings and all characters to the next control character 
such as a carriage return, are written to the report file. 

The report strings may be used to isolate the transmission rate of the modem's connect string and return the value to thechat 
user. The analysis of the report string logic occurs in conjunction with the other string processi ng such as looking for the 
expect string. The use of the same string for a report and abort sequence is probably not very useful; however, it is possible. 

The report strings do not change the completi on code of the program. 

These "report" strings may be specified in the script using the report sequence. It is written in the script as in the following 
example: 

REPORT CONNECT ABORT BUSY " ATDT5551212 CONNECT 11 ogin: account 

This sequence expects nothing and then sends the string ATDT 5551212 to dial the telephone. The expected string is connect. 

If thestring connect is received, the remainder of the script is executed. In addition, the program writes to the expect-file the 
string connect plus any characters that follow it such as the connection rate. 

TIME-OUT 

The initial time-out value is 45 seconds. This may be changed using the -t parameter. 

T 0 change the time-out value for the next expect string, the following example may be used: 

ATZ OK ATDT5551212 CONNECT TIMEOUT 10 ogin:-ogin: TIMEOUT 5 password:: hello2u2 

This changes the time-out to 10 seconds when it expects the login: prompt. The time-out is then changed to 5 seconds 
when it looks for the password prompt. 

The time-out, once changed, remains in effect until itischanged again. 

SENDING EOT 

The special reply string of eot indicates that the chat program should send an eot character to the remote. This is usually the 
E n d-of-fi I e character sequence. A return character is not sent following the eot. The eot sequence may be embedded into the 
send string using the sequence ~d. 

GENERATING BREAK 

The special reply string of break causes a break condition to be sent. The break is a special signal on the transmitter. The 
normal processing on the receiver is to change the transmission rate. It may be used to cycle through the avail able transmis¬ 
sion rates on the remote until you are able to receive a valid login prompt. T he break sequence may be embedded into the 
send string using the \k sequence. 

ESCAPE SEQUENCES 

The expect and reply strings may contain escape sequences. All the sequences are legal in the reply string. M any are legal in 
the expect. Those that are not valid in the expect sequence are so indicated. 

Expects or sends a null string. If you send a null string, it will still send the return 
character. This sequence may either be a pai r of apostrophe or quote characters. 

\\b Represents a backspace character. 
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\\c 

Suppressesthenewlineattheend of the reply string. This isthe only method to send a 
string without a trailing return character. It must beat the end of the send string. For 
example, the sequence heiio\c will simply send the characters h, e, l, i, o. (N ot valid in 
expect.) 

\\d 

Delay for one second. The program usessieep(l), which will delay to a maxi mum of 
onesecond. (N ot valid in expect.) 

UK 

InsertaBREAK. (Notvalid in expect.) 

\\n 

Send a newlineor linefeed character. 

\\N 

Send a null character. The same sequence may be represented by \e. (N ot valid in 
expect.) 

\\P 

Pausefor a fraction ofasecond. The delay is one tenth of asecond. (Notvalid in 
expect.) 

Uq 

Suppresswriting the string to thesYSLOG file. The string ?????? is written to the log in 
its pi ace. (N ot valid in expect.) 

\\r 

Send or expect a carriage return. 

\\s 

Represents a space character in the string. This may be used when it is not desirable to 
quote the strings that contai ns spaces. The sequence hi tim and hi \stim are the same. 

\\t 

Send or expect a tab character. 

\\\\ 

Send or expect a backslash character. 

\ \ddd 

Collapse the octal digits (ddd ) into a si ngle ASC 11 character and send that character. 
(Some characters are not valid in expect.) 

A C 

Substitute thesequence with thecontrol character represented bye. For example the 
character dci (17) isshown as -q. (Somecharactersarenot valid in expect.) 

TERMINATION CODES 


The chat program will terminate with thefollowing completion codes: 

0 

T he normal termination of the program. This indicates that the script was executed 
without error to the normal conclusion. 

1 

Oneormore of the parameters areinvalid or an expect string was too large for the 
internal buffers. This indicates that the program as not properly executed. 

2 

An error occurred during the execution of the program. This may be due to a read or 
write operation failing for some reason or chat receiving a signal such assiGiNT. 

3 

A time-out event occurred when there was an expect string without having a - subsend 
string. This may mean that you did not program thescript correctly for the condition or 
that some unexpected event occurred and the expected string could not be found. 

4 

Thefirst string marked as an abort condition occurred. 

5 

The second string marked as an abort condition occurred. 

6 

The third string marked as an abort condition occurred. 

7 

The fourth string marked as an abort condition occurred. 

The other termination codes are also strings marked as an abort condition. 

Using the termination code it is possible to determine which event terminated the script. It is possible to decide if the string 
busy was received from the modem as opposed to no dial tone. Although the first event may be retried, the second will 
probably have little chance of succeeding during a retry. 

SEE ALSO 


Additional information about chat scripts may be found with UUCP documentation. The chat script was taken from the 
ideas proposed by the scripts used bytheuucico program. 

uucico(l), uucp(l) 





clock 



COPYRIGHT 

The chat program is in public domain. This is not the GN U public license. If it breaks, then you get to keep both pieces. 

Chat Version 1.9, 5 M ay 1995 


chroot 

chroot— C hange root di rectory and execute a program there. 

SYNOPSIS 

chroot directory program [ arg ... ] 

DESCRIPTION 

chroot changes the root directory for a process to a new directory executes a program there. 

SEE ALSO 

chroot(2) 

AUTHOR 

Rick Sladkey( j rs@world.std.com) 

Linux0.99, 20 November 1993 


clock 

clock— M ani pulate the CMOS clock. 


SYNOPSIS 

/sbin/clock [ -u ] -r 
/sbin/clock [ -u ] -w 
/sbin/clock [ -u ] -s 
/sbin/clock [ -u ] -a 

DESCRIPTION 

clock manipulates the CM OS clock in various ways, allowing it to be read or written and allowing synchronization between 
the CM OS clock and the kernel's version of the system time. 

OPTIONS 

-u IndicatesthattheCM OS clock is set to Universal Time. 

-r Read CM OS clock and print the result to stdout. 

-w W rite the system time into the CM OS clock. 

-s Set the system time from the CM OS clock. 

-a Set the system time from the CM OS clock, adjusting the time to correct for systematic 

error and writing it back into the CM OS clock. This option uses the fi le /etc/ad j time 
to determinehow the clock changes. It contains three numbers. 

The first number is the correction in seconds per day. (For example, if your clock runs 5 
seconds fast each day, the first number should read - 5 . 0 .) 

Thesecond number tells when clock was last used in seconds since 1/1/1970. 

T he third number is the remaining part of a second that was leftover after the last 
adjustment. 
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Thefollowing instructions are from the source code: 

1. C reate afile/etc/adjtime containing asthefirst and only line 0.0 0 0 . 0 . 

2. Run clock -auor clock -a, dependingon whether your CM OS isin Universal or Local Time This updates the 
second number. 

3. Setyoursystemtimeusingthedatecommand. 

4. Update your CM OS time using clock -wu or clock -w. 

5. Replacethe first number in /etc/adjtime by your correction. 

6. Putthecommand clock -auor clock -a in your /etc/rc,local or let cron(8) start it regularly. 

FILES 

/etc/adjtime 
/etc/rc.local 

AUTHORS 

vi.o 
Vl.l 
VI.2 


comsat 

comsat — Biff server 

SYNOPSIS 

comsat 

DESCRIPTION 

comsat is the server process that receives reports of incoming mail and notifies users if they requested this service, comsat 
receives messages on a datagram port associated with the biff service specification (seeservices(5) and metd(8)). T he one- 
line m essages are of the form 

user @ma i I b o x - o f f s e t 

If the user specified is logged in to the system and the associated terminal has the owner execute bit turned on (by a biff y), 
the offset is used as a seek offset into the appropriate mailbox file and the first 7 lines or 560 characters of the message are 
printed on the user's terminal. Lines that appear to be part of the message header other than the From, T o, Date, or Subject 
lines are not included in the displayed message. 

FILES 

/var/run/utmp to find out who's logged on and on what terminals 

SEE ALSO 

biff(l), inetd(8) 

BUGS 

The message header filtering is prone to error. The density of the information presented is near the theoretical minimum. 
Users should be notified of mail that arrives on other machines than theoneto which they are currently logged in. 

The notification should appear in a separate window so it does not mess up the screen. 


C harles H edrick (hedrick@cs. rutgers. edu) Apr 1992 
M odified for clock adjustments Rob H ooft (hooft@chem. ruu .m) N ov 1992 
Patches by H arald Koenig (koenig@nova.tat. physik. uni- tuebingen.de) applied by 
Rob H ooft (hooft@EMBL-Heidelberg.DE) 0 Ct 1993 

Linux0.99, 24 December 1992 
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HISTORY 

The command appeared in BSD 4.2. 



BSD 4.2,16 March 1991 


crond 

crond—cron daemon (Dillon'sCron). 

SYNOPSIS 

crond [-1#] [ - d[#]] [- f ] [-b] [-c directory] 


OPTIONS 


crond is a background daemon that parses individual crontab files and executes commands on behalf of the users in 
question. 


- II o g I e v e I 
-d[debugl evel ] 


-f 

-b 

-c directory 


Set loggi ng level; default is 8. 

Set debugging level; default iso. If no level is specified with the -d option, the default is 
i. This option also sets the logging level to 0 and causes crond to run in the foreground. 
Run crond in the foreground. 

Run crond in the background (the default unless -d is specified). 

Specify directory containing crontab files. 


DESCRIPTION 

crond is responsible for scanning the crontab files and running their commands at the appropriate time. T he crontab 
program communicates with crond through thecron.updatefile, which residesin thecrontabs directory, usually /var/ 
spooi/cron/crontabs. This is accomplished by appending the filename of the modified or deleted crontab file to 
cron, update, which crond then picks up to resynchronize or remove its internal representation of the file. 

crond has a number of built-in limitations to reduce the chance of it being ill-used. Potentially infinite loops during parsing 
are dealt with via a fail safe counter, and user crontabs are generally limited to 256 crontab entries, crontab lines may not 
be longer than 1024 characters, including the newline 

Whena/er crond must run a job, it first creates a daemon-owned temporary fileo_ExcL and o_append to store any output, 
and then it fork os and changes its user and group permissions to match that of the user the job is being run for. Then, it 
executes /bin/sh -c to run the job. The temporary file remains under the ownership of the daemon to pra/ent the user from 
tampering with it. U pon job completion, crond verifies the secureness of the mail file and, if it has been appended to, mails 
to the file to user. The sendmaii program is run under the user's U ID to pra/ent mail-related security holes. Unlike 
crontab, the crond program does not leave an open descriptor to the file for the duration of the job's execution because this 
might cause crond to run out of descriptors. When the crontab program allows a user to edit his crontab, it copies the 
crontab to a user-owned file before running the user's preferred editor. The suid crontab program keeps an open 
descriptor to the file, which it later uses to copy the file back, thereby ensuring the user has not tampered with the file type. 

crond always synchronizes to the top of the minute, checking the current time against the list of possible jobs. The list is 
stored such that the scan goes very quickly, and crond can deal with several thousand entries without taking any noticeable 
amount of CPU. 


AUTHOR 


M atthew D i I Ion (dillon@apollo.west.oic.com) 


1 May 1994 
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ctlinnd 

ctiinnd — C ontrol the I nterN etN ews daemon. 

SYNOPSIS 

ctlinnd [ -h ] [ - s ] [ - t t i meout ] command [ ar gument ... ] 

DESCRIPTION 

ctlinnd sends a message to the control channel of innd(8), the I nterN etN ews server. 

In the normal mode of behavior, the message is sent to the server, which then performs the requested action and sends back a 
reply with atext message and theexit codefor ctiinnd. If theserver successfully performed thecommand, ctiinnd will exit 
with a status of zero and print the reply on standard output. If the server could not perform the command (for example it 
was told to remove a newsgroup that does not exist), it will direct ctiinnd to exit with a status of one. The shutdown, 
xabort, and xexec commands do not generate a reply; ctiinnd will always exit silently with a status of zero. If the -s flag is 
used, then no message will be printed if thecommand was successful. 

The-t flag can be used to specify how long to wait for the reply from theserver. The timeout value specifies the number of 
seconds to wait. A value of zero waits forever, and a value less than zero indicates that no reply is needed. When waiting for a 
reply, ctiinnd will try every two minutes to see if theserver is still running, so it is unlikely that -to will hang. The default 
is-t0. 

T o see a command summary, use the-h flag. If a command is included when ctiinnd is invoked with the-h flag, then only 
th e u sage fo r th at comm an d wi 11 be gi ven. 

If a large number of groups are going to be created or deleted at once, it may be more efficient to pause or throttle the server 
and edit the active file directly. 

The complete list of commands follows. Note that all commands have a fixed number of arguments. If a parameter can bean 
empty string, then it is necessary to specify it as two adjacent quotes (■ ■). 

addhistMessage-1 Darr exp post paths Add an entry to the history database. T his di rects the server to create a 

history line for M essage-ID. The angle brackets are optional, ar r, exp, and 
post specify when the article arrived, what its expiration date is, and when it 
was posted. All three values are a number indicating the number of seconds 
si nee the epoch. If thearticledoes not have an Expires header, then exp 
should be zero, paths isthe pathname within thenewsspool directory where 
the article isfiled. If the article is cross-posted, then the names should be 
separated by whitespace and the pat hs argument should be inside double 
quotes. If theserver is paused or throttled, this command causes it to briefly 
open the history database. 

allow r e a s o n R emote connecti ons are al lowed. T he reason m ust be the same text gi ven 

with an earlier reject command or an empty string. 

begin site Begi n feeding s i t e. T his will cause the server to rescan thenewsfeeds(5) file 

to find the specified site and set up a newsfeed for it. If the site already exists, 
a "drop" isdonefirst. Thiscommand isforwarded; see below. 

cancel <Message-1 d> Remove the article with the specified M essage-l D from the local system. This 

does not generate a cancel message. The angle brackets are optional. If the 
server is paused or throttled, thiscommand causes it to briefly open the 
history database. 

changegroup group rest T he newsgroup group is changed so that its fourth field in the active file 

becomes the value specified by the rest parameter. This may be used to make 
an existing group moderated or unmoderated, for example. 

checktiie C heck the syntax of the newsfeeds file, and display a message if any errors are 

found. T he details of the errors are reported to sysiog(3). 
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drop site 
flush site 


flushlogs 
go reason 


hangup channel 

help [command] 
mode 

name nnn 

newgroup group rest creator 


param letter value 


pause reason 


readers flag text 


Flush and drop site from the server's list of active feeds. This command is 
forwarded; see below. 

Flush the buffer for the specified si te. The actions taken depend on the type 
offeed the site receives; see newsfeeds(5). This is useful when the site is fed 
by a file and batching is going to start. If site is an empty string, then all sites 
are flushed and the active file and history databases are also written out. This 
command is forwarded; see below. 

Close the log and error log files and rename them to have a .old extension. 
The history database and active file are also written out. 

Reopen the history database and start accepting articles after a pause or 
throttle command. The reason must either bean empty string or match the 
text that was given in the earlier pause or throttle command. Ifarqect 
command was done, thiswill also do an allow command if the reason 
matches the text that was given in the rqect. If a reserve command was done, 
thiswill also clear the reservation if the reason matches the text that was given 
in the reserve. N otethat if only the history database has changed while the 
server is paused or throttled, it is not necessary to send it a reload command 
before sending it a go command. If the server throttled itself because it 
accumulated too many I/O errors, this command will reset the error count. If 
the server was not started with the -ny flag, then thiscommand also does a 
readers command with yes as the flag and reason as the text. 

Close the socket on the specified incoming channel . This is useful when an 
incoming connection appears to be hung. 

Printacommand summary for all commands, or just command if specified. 
Print the server's operati ng mode as a multil ine summary of the parameters 
and operating state. 

Print the name of channel numbernnn or of all channels if it isan empty 
string. 

Create the specified newsgroup. T her est parameter should be the fourth 
field as described in active(5); if it is not an equal sign, only the first letter is 
used. T he c r eat or should bethenameof the person creating thegroup. Ifthe 
newsgroup already exists, this is equivalent to the changegroup command. 

T his isthe only command that has defaults The creator can be omitted and 
will default to the empty string, and thereat parameter can be omitted and 
will default to y. This command can be done while the server is paused or 
throttled; it will update its internal state when a go command is sent. This 
command updatestheactive.times (seeactive(5))file. 

C hange the command-line parameters of the server. T he combination of 
defaults makes it possible to use the text of the C ontrol header directly, 
letter isthe innd command-1 ine option to set, and value isthe new value. 

For example, i s directs the server to allow only five incoming connections. 

T o enable or disable the action of the-n flag, use the letter y or n for the 
val ue. 

Pause the server so that no incoming articles are accepted. N o existing 
connecti ons are closed, but the history database is closed. This command 
should be used for short-term locks, such as when replacing the history files. 

If the server was not started with the-ny flag, then thiscommand also does a 
readers command with no as the flag and reason as the text. 

Allow or disallow newsreaders. If f i ag starts with the letter n, then 
newsreading is disallowed by causing the server to pass the text as the value of 
the nnrpd(8) -r flag. If f i ag starts with the letter y and text is either an empty 
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reject reason 
reload what reason 


renumber group 

reserve reason 


rmgroup group 


send feed text... 
shutdown reason 

signal s i g site 

throttle reason 


trace item flag 


xabort reason 
xexec path 


string, or the same string that was used when newsreading was disallowed, 
then newsreading will be allowed. 

Remote connections (those that would not be handed offtonnrpd) are 
rejected, with reason given as the explanation. 

The server updates its in-memory copies of various configuration files, what 
identifies what should be reloaded. If it is an empty string or the word ail, 
then everything is reloaded; if it istheword history, then the histo ry 
database is closed and opened; if it istheword hosts, nntp, then the 
hosts. nntp(5) file is reloaded; if it is the word active or newsf eeds, then 
both the active and newsfeeds fi les are reloaded; if it istheword 
overview.fmt, then the overview.f mt(5) file is reloaded. T he r eas on is 
reported to sysiog. There is no way to reload the data inn.conf(5) file; the 
server currently only uses the pathhost parameter, so this restriction should 
not be a problem. 

Scan the spool directory for the specified newsgroup and update the low- 
water mark in the active file. If group isan empty string, then all newsgroups 
are scanned. 

The next pause or throttle command must use r e a s o n as its text. This 
reservation iscleared by giving an empty string for thereason. This 
command is used by programs such asexpire(8) that want to avoid running 
into other instances of each other. 

Remove the specified newsgroup. This is done by editing the active file. The 
spool directory is not touched, and any articles in the group will be expired 
using the default expiration parameters. Uni ike the newg roup command, this 
command does not update the active, times file. 

T he specified text is sent as a control line to the exploder feed. 

The server isshut down, with the specified reason recorded in the log and 
sent to all open connections. It isagood idea to send a throttle command 
first. 

Signal si g is sent to the specified site, which must be a channel or exploder 
feed, si g can bea numeric signal number ortheword pup, int, or term; case 
is not significant. 

Input is throttled so that all existing connections are closed and new 
connections are rejected. The history database is closed. This should be used 
for long-term locks, such as when expire isbeing run. Ifthe server was not 
started with the-ny flag, then this command also does a readers command 
with no astheflag and reason asthetext. 

T racing is turned on or off for the specified item, flag should start with the 
letter y or n to turn tracing on or off. If tem starts as a number, then tracing 
is set for the specified innd channel, which must be for an incoming NNTP 
feed. If it starts with the letter i, then general innd tracing is turned on or off. 
If it starts with the letter n, then future nnrpd's will or will not have the -t 
flag enabled, as appropriate. 

The server logs the specified reason and then invokes the abort(3) routine. 
The server gets ready to shut itself down, but instead of exiting, it executes 
thespecified path with all of itsoriginal arguments. If path is innd, then / 
news/bin/innd is invoked; if it is inndstart, then / news / bin/inndst ant is 
invoked; if it isan empty string, itwill invoke the appropri ate program 
depending on whether it was started with the-p flag; any other value isan 
error. 
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In addition to being acted upon within theserver, certain commands can be forwarded to the appropriate chi Id process. If 
the site receiving the command is an exploder (such asbuftchan(8)) or it is a funnel that feeds into an exploder, then the 
command can be forwarded. In this case, theserver will send a command line to the exploder that consists of the ctiinnd 
command name. If the site funnels into an exploder that has an asterisk (*) in its w flag (seenewsfeed(5)), then the site name 
isappended to thecommand; otherwise, no argument isappended. 

BUGS 

ctiinnd usesthe inndcomm(3) library and is therefore limited to server replies no larger than 4KB. 

HISTORY 

W ritten by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

active(5), expire(8), innd(8), inndcomm(3), inn.conf(5), newsf eeds(5), overview.fmt(5) 

ctrlaltdel 

ctriaitdei— Set the function of the Ctrl-hAlt-HD el combination. 

SYNOPSIS 

ctrlaltdel hard|soft 

DESCRIPTION 

Based on examination of theiinux/kernei/sys.c code, it isclear that there are two supported functionsthatthe 
C trl+Alt+D el sequence can perform: a hard reset, which immediately reboots the computer without calling sync(2) and 
without any other preparation, and a soft reset, which sends the sigint (interrupt) signal to theimt process (this is always 
the process with PID 1). If this option is used, theimt(8) program must support this feature. Becausetherearenow several 
imt(8) programs in the Linux community, consult the documentation for the version that you are currently using. 

ctrlaltdel is usually used i n the /etc/rc. local file. 

FILES 

/etc/rc.local 

SEE ALSO 

simpleinit(8), init(8) 

AUTHOR 

Peter 0 rbaek (poe@daimi.aau.dk) 

Linux 0.99, 25 October 1993 


cvsbug 

cvsbug—Send problem report (PR) about C VS to a central support site. 

SYNOPSIS 


cvsbug [ site ][-f probl em- report ][-t ma i I -address ][-P ] [ - L ] 
[ - -r equest • i d ] [ -v ] 
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DESCRIPTION 

cvsbug is a tool used to submit problem reports (P Rs) to a central support site. In most cases, the correct site will be the 
default. This argument indicates the support site that is responsible for the category of problem involved. Some sites may use 
a local address as a default. Site values are defined by using the aiiases(5). 

cvsbug invokes an editor on a problem report template (after trying to fill in some fields with reasonable default values). 
When you exit the editor, cvsbug sends the completed form to the Problem Report M an agement System (GNATS) at a 
central support site. At the support site, thePR is assigned a unique number and isstored in theGNATS database according 
to its category and submitter ID. GNATS automatically replies with an acknowledgment, citing the category and thePR 
number. 

To ensure that a PR ishandled promptly, it should contain your (unique) submitter ID and one of the available categories to 
identify the problem area. (Use cvsbug -l to see a list of categories.) 

The cvsbug template at your site should already be customized with your submitter ID (running install -sid submitter-id 
to accomplish this is part of the installation procedures for cvsbug). If this hasn't been done see your system administrator 
for your submitter ID, or request one from your support site by invoking cvsbug - - request-id. If your site does not 
distinguish between different user sites, or if you are not affiliated with the support site, Usenet for this field. 

The more precise your problem description and the more complete your information, the faster your support team can solve 
your problems. 

OPTIONS 

-f problem-report 


-1 mai I - address 


-P 


--request-id 


Specify a file (pr obi cm- report) that already contains a complete problem report, cvsbug 
sends the contents of the file without invoking the editor. If the value for pro bi em- report 
is-, then cvsbug reads from standard input. 

Change mai I address at the support site for problem reports The default mai i - address is 
the address used for the default site U se the site argument rather than this option in 
nearly all cases. 

Print the form specified by the environment variable pr form on standard output. If pr 
form is not set, print the standard blank PR template. No mail is sent. 

Print the list of available categories. Nomail is sent. 

Sends mail to the default support site, or si te if specified, with a request for your 
submitter ID. If you are not affiliated with si te, use a submitter ID of net. 

D isplay the cvsbug version number. 


N ote: Use cvsbug to submit problem reports rather than mail them directly. Using both the template and cvsbug itself will 
help ensure all necessary information will reach the support site. 


ENVIRONMENT 

T he environment variable editor specifies the editor to invoke on the template. T he default is vi. 

If the environment variable pr form is set, then its value is used as the filename of the template for your problem-report 
editing session. You can use this to start with a partially completed form (for example, a form with the identification fields 
already completed). 


HOWTO FILL OUT A PROBLEM REPORT 

Problem reports have to be in a particular form so that a program can easily manage them. Please remember the following 
guidelines: 

Describe only one problem with each problem report. 

Forfollow-up mail, usethesamesubject lineastheonein theautomatic acknowledgment. It consists of category, PR 
number, and theoriginal synopsis line This allows the support site to relate several mail messages to a particular PR and 
to record them automatically. 
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Please try to be as accurate as possible in the subject or synopsis line. 

The subject and the synopsis line are not confidential. This is because open-bugs lists are compiled from them. Avoid 
putting confidential information there. 

See the GN U Info file cvsbug. info or the document Reporting ProblemsWith cvsbug for detailed information on reporting 
problems 

H0 W TO SU BM IT TEST CASES, CO DE, AN D SO 0 N 

Submit small code samples with the PR. Contact the support site for instructions on submitting larger test cases and 
problematic source code. 

FILES 

/tmp/p$$ copy of PR used in editing session 
/tmp/pt$$ copy of empty PR form, fortesting purposes 
/tmp/pbad$$ file for rejected PRs 

EMACSUSER INTERFACE 

An EM ACS user interface for cvsbug with completion of field values is part of the cvsbug distribution (invoked with m-x 
cvsbug). See the file cvsbug. info or the ASC11 file install in the top-level directory of the distribution for configuration 
and installation information. The EM ACS LISP template file is cvsbug -ei. in and is installed as cvsbug. ei. 

INSTALLATION AND CONFIGURATION 

See cvsbug. info orINsTALL for installation instructions 

SEE ALSO 

Reporting ProblemsU sing cvsbug (also installed astheGN U Info filecvsbug.info). 

gnats(l), queny-pn(l), edit-pr(l), gnats(8), queue-pr(8), at-pr(8), mkcat(8), mkdist(8) 

AUTHORS 

Jeffrey Osier, Brendan Kehoe,Jason Merrill, HeinzG. Seidl (Cygnus Support). 

COPYING 

Copyright(c) 1992,1993 Free Software Foundation, Inc. Permission isgranted to make and distribute verbatim copiesof 
this manual provided the copyright notice and this permission notice are preserved on all copies. 

Permission isgranted to copy and distribute modified versions of this manual under the conditions for verbatim copying, 
provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. 

Permission isgranted to copy and distribute translations of this manual into another language, under the above conditions 
for modified versions, except that this permission notice may be included in translations approved by the Free Software 
Foundation instead of in the original English. 

xVERSIONx, February 1993 


cvtbatch 

cvtbatcb— Convert Usenet batch file to IN N format. 

SYNOPSIS 


cvtbatch [ -w i t e ms ] 
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DESCRIPTION 

cvtbatch reads standard input as a series of lines, converts each line, and writes it to standard output. It is used to convert 
si mple batchfiles that contain just the article name to IN N batchfiles that contain additional information about each article. 

Each line is taken as the path name to a Usenet article. If it is not an absolute pathname, it is taken relative to the spool 
directory, /news/spool. (Only the first word of each lineis parsed; anything following whitespace is ignored.) 

T he-w flag specifies how each output line should be written. The items forthisflag should be chosen from the w flag items 
as specified in newsfeeds(5). They may be chosen from the following set: 

b Size of article in bytes 

t Full pathnameof article 

m Article M essage-ID 

n Relative pathname of article 

If the input file consists of a series of M essage-IDs, then usegrephistbr-y(l) with the-s flag piped into cvtbatcb. 

HISTORY 

W ritten by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

grephistery(l) newsfeeds(5) 

cytune 

cytune— T une Cyclades driver parameters. 

SYNOPSIS 

cytune [-q [-i interval ]] ([-s value]|[-S value]) 

[ - g | G ] ([-t timeout]][-T timeout]) tty [tty ... ] 

DESCRIPTION 

cytune queries and modifies the interruption threshold for the Cyclades driver. Each serial line on a Cyclades card has a 12- 
byte FIFO for input (and another 12-byte FIFO for output). The "threshold" specifies how many input characters must be 
present in the FIFO before an interruption is raised. W hen a Cyclades tty is opened, this threshold is set to a default value 
based on baud rate 

Baud Thrediold 

50-4800 
9600 
19200 
38400 

57600-150000 

If the threshold is set too low, the large number of interruptions can load the machine and decrease overall system through¬ 
put. If the threshold is set too high, the FIFO buffer can overflow, and characters will be lost. Slower machines, however, 
may not be able to deal with the interrupt load and will require that the threshold be adjusted upwards. 

If the Cyclades driver was compiled with enable monitoring defined, the cytune command can be used with the -q option 
to report interrupts over the monitoring interval and characters transferred over the monitoring interval. It will also report 


10 

8 

4 

2 

1 
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the state of the FIFO. The maxi mum number of characters in the FIFO when an interrupt occurred, the instantaneous 
count of characters in the FIFO, and how many characters are now in the FIFO are reported. This output might look like 
this: 

/dev/cubC0: 830 ints, 9130 chars; fifo: 11 threshold, 11 max, 11 now 
166.259866 interrupts/second, 1828.858521 characters/second 

This output indicates that for this monitoring period, the interrupts were always being handled within one character time 
because max na/er rose above threshold. T his is good, and you can probably run this way, provided that a large number of 
samples come out this way. You will lose characters if you overrun the FIFO because the Cyclades hardware does not seem to 
support the RTS RS-232 signal line for hardware flow control from the DC E to the DTE. 

cytune will in query mode produce a summary report when ended with a sigint or when the threshold or time-out is 
changed. 

There may be a responsiveness versus through put tradeoff. T he Cyclades card, at the higher speeds, is capable of putting a 
very high interrupt load on the system. This will reduce the amount of CPU time avail able for other tasks on your system. 

FI owever, the time it takes to respond to a single character may be increased if you increase the threshold. This might be 
noticed by monitoring ping(8) times on a SLIP link controlled by a Cyclades card. If your SLIP link is generally used for 
interactive work such asteinet(l), you might want to leave the threshold low so that characters are responded to as quickly 
as possible. If your SLIP link is generally used for file transfer, WWW, and the like, setting the FIFO to a high value is likely 
to reduce the load on your system while not significantly affecting throughput. Alternatively, seethe -t or -t options to 
adjust the time that the Cyclades waits before flushing its buffer. U nits are 5ms. 

If you are running a mouse on a Cyclades port, it is likely that you want to maintain the threshold and time-out at a low 
value. 

OPTIONS 

-s value 

-t value 


-g 

-T val ue 

-G 

-q 

-i interval 

BUGS 

If you run two copies of cytune atthesametimeto report statistics about the same port, themts, chars, and max values will 
be reset and not reported correctly. cytune(8) should pra/ent this but does not. 

AUTHOR 

N ick Simicich (njs@scifi.emi. net), with modifications by Rik Faith (faith@cs. unc.edu) 


Set the current threshold to va i ue characters. N otethat if the tty is not being held open 
by another process, the threshold will be reset on the next open. 0 nly values between i 
and 12 , inclusive are permitted. 

Set the current flush timeout to value units. N otethat if the tty is not being held open 
by another process, the threshold will be reset on the next open. 0 nly values between 0 
and 255 , inclusive, are permitted. Setting value to 0 forces the default, currently 0 x 20 
(160ms) but soon to be@x 02 (10ms). Units are5ms. 

G et the current threshold and ti me-out. 

Set the default flush time-out to value units When the tty is next opened, this value is 
used instead of the default. I f value is 0 , then the value defaults to 0 x 20 (160ms), soon to 
be 0 x 02 (10ms). 

Get the default threshold and flush time-out values. 

G ather statistics about the tty. T he results are only valid if the C yclades driver has been 
compiled with enable monitoring defined. Thisisprobably not the default. 

Statistics will be gathered every i nter vai seconds. 
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FILES 

/dev/ttyC[0-8] 

/dev/cubC[0-8] 

SEE ALSO 

setserial(8) 


4 March 1995 


debugfs 

debugfs— ext 2 filesystem debugger. 

SYNOPSIS 

debugfs [[-w ]device ] 

DESCRIPTION 

debugfs is a filesystem debugger. It can be used to examine and change the state of an ext 2 filesystem, device is the special 
file corresponding to the device containing the ext 2 filesystem (such as/dev/hdxx). 

OPTIONS 

-w Specify that the filesystem should be open in read-write mode. Without thisoption, 

the filesystem isopen in read-only mode. 


COMMANDS 

debugfs is an interactive debugger. It understands a number of commands: 


cd file 

chroot file 

close 

clri file 

expand_dir, file 

find_free_block [goal ] 

find_free_inode [dir [mode]] 

f reeb block 

freei file 

help 

iname inode 

initialize device blocksize 
kill_file file 
In sourcefiI e dest_fiI e 
Is [pat hname ] 

Modify_inode file 

mkdir file 

open [ -w] device 

pwd 

quit 


Close the currently open filesystem. 

Clear the contents of the inode corresponding to fi i e. 

Expand a directory. 

Find the first free block, starting from goal , and allocate it. 

Find afreeinode and allocate it. 

M ark the block as not allocated. 

Free the inode corresponding ton ie. 

Print the filename corresponding to i node (currently not implemented). 
Create an ext 2 filesystem on devi ce. 

Remove a fi le and deallocate its blocks 
Create a link. 

Emulate the is(l) command. 

M odify the contents of the inode corresponding ton i e. 

M ake a di rectory. 

Open a filesystem. 


Q uit debugfs. 
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rm file 
rmdir file 
setb bl ock 
seti file 
show_super_stats 
stat file 
testb bl ock 
testi file 
unlink file 


Remove a file. 

Remove a directory. 

M ark the bl ock as allocated. 

M ark in use the inode corresponding to file 
List the contents of the super block. 

Dump the contents of theinode corresponding to f i i e. 

T est if the block is marked as allocated. 

T est if the inode corresponding to fi i e is marked as allocated. 
Remove a link. 


AUTHOR 

debugts was written byTheodoreT'so (tytso@mit.edu). 

SEE ALSO 

dumpe2fs(8), e2fsck(8), mke2fs(8) 

Version 0.5b , N ovember 1994 


dip 

dip— D ialup IP connection handler. 

SYNOPSIS 

dip [-t] 

dip [ -ktv] [ -m mt u ] s c r i pt f i I e 
dip [ -iv] [user_name ] 

DESCRIPTION 

dip handles the connections needed for dialup IP links, such as SLIP or PPP. It can handle both incoming and outgoing 
connections, using password security for incoming connections. The outgoing connections use the system's diai(3) library 
if available. 

COMMAND MODE 

The first possible use of dip is as a stand-alone program to set up an outgoing IP connection. This can be done by invoking 
dip with the -t option, which means enter test mode and, more precisely, dump you in the command-mode of the dip 
program. You are reminded of this by the dip> prompt, or, if you also specified the -v debugging flag, the dip [nnnn ] > 
prompt. The latter prompt also displaysthe current value of the global errivi variable which is used mostly when dip runs 
in script mode. For the interactive mode it can be used to determi ne if the result of the previous command wasokay. 

The foil owing is a sample taken from a live session: 

$dip-t 

DIP: Dialup IP Protocol Driver version 3.3.7 (12/13/93) 

Written by Fred N. van Kempen, MicroWalt Corporation. 

DIP>_ 

The most helpful command in this mode is, of course, the help command, which should produce an output similar to this: 

DIP> help 

DIP knows about the following commands: 
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databits default dial echo flush 
get goto help if init 
mode modem parity print port 
reset send sleep speed stopbits 
term wait 

DIP>_ 

All commands display how they should be used when invoking them with no or invalid arguments. Just experiment a little to 
get the feel of it, and have a look at the sample script files, which also use this command language. 

DIALIN MODE 

The second possibleway of using dip is as a login shell for incoming IP connections, as in dialup SLIP and PPP connections. 
T o make integration into the existing UNIX system as easy as possible, dip can be installed as simply as using it as a login 
shell in the system's password file. A sample entry looks like 

suunet:ij/SMxiTIGVCo:1004:10:UUNET:/tmp:/usr/bin/dip -i 

When user suunet logs in, the iogin(l) program sets the home directory to / tmp and execute the dip program with the -i 
option, which means that dip must run in input mode, dip then tries to locate the name of the logged-in user (the name 
corresponding to its current user ID, as returned by thegetuid(2) system call) in its database file. An optional single 
argument to the dip program in thismodecan be the username that must be used in thislookup, regardless of the current 
user ID. 

dip now scans the / etc/net/diphosts file for an entry for the given username. This file contains lines of text (much like the 
standard password file). Theformat lookslike 
# 

# diphosts This file describes a number of name to 

# address mappings for the DIP program. It 

# is used to determine which IP address to 

# use for in incoming call of some user. 

# 

# Version: @(#)diphosts 1.00 12/10/92 FvK 

# 

# Author: Fred N. van Kempen, 

# <waltje@uwalt.nl.mugnet.org> 

# 

suunet::uunet.uu.net:UUNET SLIP:SLIP,296 
# End of diphosts. 

The first field of a line identifies the username, which you must match. The second field can contain an encrypted password. 
If thisfield is non-null, thedip program asks for an external security password, which must match the password in this field. 
The third field contains the name (or raw IP address) of the host that is connecting to the system with this link. If a 
hostname is given, the usual address resolving process is started, using either a nameserver or a local hosts file. 

The fourth field can contain any text; it is not (yet) used by thedip program. In future releases, this info may be used in the 
system log files. Finally, the fifth field of a line contains a mixture of comm a-separated flags. Possibleflags are 

slip to indicate you must usetheSLIP protocol. 

ppp to indicate you must use the PPP protocol. 

number, whichgivestheMTUparameterofthisconnection. 

After finding the correct line, dip puts the terminal line into RAW mode and asks the system networking layer to allocate a 
channel of the desired protocol. Finally, ifthechannel isactivated, itaddsan entry to thesystem'sroutingtableto makethe 
connection work. 
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dip now goes into an endless loop of sleeping, which continues until the connection is physically aborted (the line is 
dropped). At that time, dip removes the entry it made in the system's routing table and releases the protocol channel for 
reuse. It then exits, making room for another session. 

DIALOUTMODE 

The last way of using dip is as a program that initiates outgoing connections. T o make life easier for the people who have to 
manage links of this type, dip uses a chat script to set up a link to a remote system. This gives the user an enormous amount 
of flexibility when making the connection, which otherwise could require many command-line options. The pathnameof 
the script to be run is then given as the single argument to dip; the program will automatically check if the file has a filename 
ending in a .dip part. This is not mandatory—just a tool to group scripts together in a single directory. A script should look 
something likethis: 

# 

# sample.dip Dialup IP connection support program. 

# This file (should show) shows how to use the DIP 

# scripting commands to establish a link to a host. 

# This host runs the 386bsd operating system, and 

# thus can only be used for the "static" addresses. 

# 

# NOTE: We also need an examnple of a script used to 

# connect to a "dynamic" SLIP server, like an Annex 

# terminal server... 

# 

# Version: @(#)sample.dip 1.30 07/05/93 

# 

# Author: Fred N. van Kempen, <waltje@uWalt.NL.Mugnet.ORG> 

# 

main: 

# First of all, set up our name for this connection. 

# I am called "uwalt.hacktic.nl" (== 193.78.33.238) 
get $local uwalt.hacktic.nl 

# Next, set up the other side's name and address. 

# My dialin machine is called 'xs4all.hacktic.nl' (== 193.78.33.42) 
get $remote xs4all.hacktic.nl 

# Set the desired serial port and speed, 
port cua0 

speed 38400 

# Reset the modem and terminal line. 

# This seems to cause trouble for some people! 
reset 

# Prepare for dialing, 
send ATQ0V1E1X1 

wait OK 2 

if $errlvl != 0 goto error 
dial 555-1234567 
if $errlvl != 0 goto error 
wait CONNECT 60 
if $errlvl != 0 goto error 

# We are connected. Login to the system, 
login: 

sleep 3 
send \r\n\r\n 
wait ogin: 10 

if $errlvl != 0 goto error 
send N0-WAY\n 
wait ord: 5 

if $errlvl != 0 goto error 
send HA-HA\n 
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wait $ 30 

if $errlvl != 0 goto error 
loggedin: 

# We are now logged in. Start the 'sliplogin' program, 

# as this is not automatically done for me. 
send sliplogin\n 

wait SOME-STRING 15 

# Set up the SLIP operating parameters, 
get $mtu 1500 

# Set Destination net/address as type 'default' (vice an address). 

# This is used by the 'route' command to set the kernel routing table. 

# Some machines seem to require this be done for SLIP to work properly, 
default 

# Say hello and fire up! 
done: 

print CONNECTED to $remote with address $rmtip 
mode SLIP 
goto exit 
error: 

print SLIP to $remote failed, 
exit: 

This script causes dip to dial up a host, log in, and get a SLIP interface channel going (in the same manner as with incoming 
connections). When all is set up, it simply goes into the background and waits for a hangup (or just a lethal signal), at which 
it hangs up and exits. 

FILES 

/etc/passwd 

/etc/diphosts 

AUTHORS 

Fred N . van Kernpen (waltje@uwalt.nl.mugnet.org), Paul M OSSip (mossip@vizlab. rutgers. edu), J eff U phoff 
(juphoff@aoc.nrao.edu), Jim Seagrave( jes@grendel.demon.co.uk), 0 laf Kirch (okir@monad.sub.de). 

Version 3.3.7,13 December 1993 


dmesg 

dmesg — Print or control the kernel ring buffer. 

SYNOPSIS 

dmesg [ -c ] [ -n level ] 

DESCRIPTION 

dmesg is used to examine or control the kernel ring buffer. 

The program helps users to print their bootup messages. Instead of copying the messages by hand, the user need only 

dmesg > boat.messages 

and mail the boot .messages fileto whoever can debug their problem. 
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OPTIONS 

Clear thering buffer contents after printing. 

Set the level at which logging of messages is doneto the console. For example, -n i 
prevents all messages, except panic messages, from appearing on theconsole. All 
levels of messages are still written to /proc/kmsg, so sysiogd(8) can still be used to 
control exactly where kernel messages appear. When the -n option is used, dmesg 
will not print or clear the kernel ring buffer. 

When both options are used, only the last option on thecommand linewill have an effect. 

SEE ALSO 

syslogd(8) 

AUTHOR 

TheodoreTs'o (tytso@athena.mit.edu) 

Linux 0.99, 28 October 1993 


-c 

-n level 


dumpe2fs 

dumpe 2 ts— Dumpfilesystem information. 

SYNOPSIS 

dumpe2fs device 

DESCRIPTION 

dumpe 2 ts prints the super block and blocks group information for the filesystem present on device. 
dumpe 2 t s is similar to Berkeley's dumpts program for the BSD Fast File System. 

BUGS 

You need to know the physical filesystem structure to understand the output. 

AUTHOR 

dumpe 2 f s was written by Remy Card (card@masi.ibp.fr), the developer and maintainer of theext 2 fs. 

AVAILABILITY 

dumpe 2 f s is available for anonymous FT P from ftp. ibp. f r and tsx - 11 . mit. edu in / pub / linux / packages/ ext 2 f s. 

SEE ALSO 

e2fsck(8), mke2fs(8), tune2fs(8) 

Verson 0.5b, N ovember 1994 


e2fsck 

e 2 fsck— C heck a Linux second extended filesystem. 

SYNOPSIS 


e2fsck [ -panyrdfvtFV ][-b superblock ][-B blocksize ] 
[ -1! -L bad_bI ocks_f i I e ] devi ce 
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DESCRIPTION 

e 2 fsck isused to check a Linux second extended filesystem. 

devi c e T he special file corresponding to the device (such as/dev/hdxx). 


OPTIONS 

-a 


-b superbl ock 


-B bl ocksi ze 


-d 

-f 

-F 

-1 f i I e n a me 
- L f i I e n a me 


-P 
- r 


-t 


- v 
-V 


-y 


This option does the same thing as the - p option. It is provided for backwards 
compatibility only; it is suggested that people use -p option whenever possible. 
Instead of using the normal superblock, use the alternative superblock specified by 

super block. 

Usually, e 2 fsck will search for the superblock at various different block sizes in an 
attempt to find the appropriate block size. This search can befooled in some cases. 
This option forces e 2 f sck to only try locating the superblock at a particular 
bi ocksi ze. If the superblock is not found, e 2 fsck will terminate with a fatal error. 
Print debugging output (useless unless you are debugging e 2 fsck). 

Force checking even if the filesystem seemsclean. 

Flush th e f i I esystem device's buffer caches before beginning. Only really useful for 
doing e 2 tsck time trials 

Add the blocks listed in the file specified by filename to the list of bad blocks. 

Set the bad blocks list to be the list of blocks specified by f i i ename. (This option is 
the same as the -l option except the bad blocks list iscleared before the blocks listed 
in thefile are added to the bad blocks list.) 

Open th e f i I esystem read-only, and assumean answer of "no" to all questions. 

Allows e 2 f sck to be used non-interactively. (N ote: if the -1 or -l options are 
specified in addition to the -n option, then the filesystem will beopened read-write 
to permit the bad-blocks list to be updated. H owever, no other changes will be made 
to the filesystem.) 

Automatically repair ("preen") thefilesystem without any questions. 

This option does nothing at all; it is provided only for backwards compatibility. 

Print timing statistics for e 2 fsck. If this option is used twice, additional timing 
statistics are printed on a pass-by-pass basis. 

V erbose mode. 

Print version information and exit. 

Assumean answer of "yes" to all questions; allows e 2 f sck to be used non- 
interactively. 


EXIT CODE 

The exit code returned bye 2 tsck isthesum of the following conditions: 


0 

1 

2 

4 

8 

16 

128 


N o errors 

F i I esystem erro rs co rrected 

Filesystem errors corrected; system should be rebooted if filesystem was mounted 
Filesystem errors left uncorrected 
Operational error 
U sage or syntax error 
Shared library error 



edquota 



BUGS 

Almost any piece of software will have bugs. If you manage to find a filesystem that causes e 2 tsck to crash, orthate 2 fsck is 
unable to repair, please report it to the author. 

Please include as much information as possible in your bug report. Ideally, include a complete transcript of thee 2 fsck run, 
so I can see exactly what error messages are displayed. If you have a writeable filesystem where the transcript can be stored, 
the script(l) program is a handy way to save the output of e 2 fsck to a file. 

It is also useful to send the output of dumpe 2 fs( 8 ). If a specific inode or inodes seems to be giving e 2 fsck trouble, try 
running the debugts( 8 ) command and send the output of thestat command run on the relevant inodes. If the inode is a 
directory, thedebugts dump command will allow you to extract the contents of the directory inode, which can sent to me 
after being first run through uuencode(l). 

Always include the full version string that e 2 fsck displays when it is run so I know which version you are running. 

AUTHOR 

T his version of e 2 tsck is written byTheodoreT s'o (tytso@mit.edu). 

SEE ALSO 

mke2fs(8), tune2fs(8), dumpe2fs(8), debugfs(8) 

Version 0.5b, N ovemberl994 


edquota 

edguota— Edit user quotas. 

SYNOPSIS 

/usr/etc/edquota [ -p proto-user ][ - ug ] name... 

/usr/etc/edquota [ -ug ] -t 

DESCRIPTION 

edquota is a quota editor. One or more users or groups may be specified on the command line. For each user or group, a 
temporary file iscreated with an ASCII representation of the current disk quotas for that user or group and an editor isthen 
invoked on the file The quotas may then be modified, new quotas added, and so on. U pon leaving the editor, edquota reads 
the temporary file and modifies the binary quota files to reflect the changes made. 

Theeditor invoked isvi(l) unless the environment variablespecifiesotherwise. 

Only the superuser may edit quotas. (For quotas to be established on a filesystem, the root directory of the filesystem must 
contain afile, owned by root, called quota.user or quota.group. Seequotaon(8) for details.) 


OPTIONS 


-U 

Edit the userquota. T his is the default. 

-g 

Edit the groupquota. 

-P 

D uplicate the quotas of the prototypical user specified for each user specified. This is 
the normal mechanism used to initialize quotas for groups of users. 

-t 

Edit the soft time limits for each filesystem. If the time limits are zero, the default 
timelimitsin <iinux/quota.h> areused. Timeunitsof sec(onds), min(utes), 
hour(s), day(s), week(s), and month(s) are understood. Timelimits are printed in the 
greatest possible time unit such that the value is greater than or equal to one 
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FILES 

quota, user- or quota, group 0 uota file at the filesystem root 

/etc/mtab M ounted filesystems 

SEE ALSO 

quota(l), vi(l), quotactl(2), quotacheck(8), quotaon(8), repquota(8) 

BUGS 

T he format of the temporary file is inscrutable. 

8Junel993 


expire 

expire— U senet article and history expiration program. 

SYNOPSIS 

expire [ -d dir ] [-f file ] [-g file ] [ -h file ] 

[-i ][-1 ][ -n ][-p ][ -q ][ -r reason ][-s ][-t ] 

[ - v level ][-w number ][-x ][-z file ][expire.ctl] 


DESCRIPTION 

expire scansthe history(5) text file /news/iib/history and uses the information recorded in it to purgeold news articles. 

T o specify an alternate history file, use the-f flag. T o specify an alternate input text history file, use the-b flag, expire uses 
the old dbz(3z) database to determine the size of the new one. T o ignore the old database, use the -i flag. 

expire usually just uni inks each file if it should be expired. If the -1 flag is used, then all articles after the first one are treated 
as if they could be symbolic links to the first one. In this case, the first article will not be removed as long as any other cross- 
posts of th e arti cl e rem ai n. 

expire usually sends a pause command to the local innd(8) daemon when it needs exclusive access to the history file, using 
the string Expiring as the reason. T o give a different reason, use the -r flag. The process ID will be appended to the reason. 
When expire is finished and the new history file is ready, it sends a go command. If innd is not running, use the -n flag and 
expire will not send the pause or go commands. (For more details on the commands, seectiinnd(8).) N otethat expire 
only needs exclusive access for a very short time— long enough to see if any new articles arrived since it first hit the end of the 
file and to renamethenew files to the working files. 

If the -s flag is used, then expire will print a summary when it exits, showing the approximate number of kilobytes used by 
all deleted articles. 

If the-t flag is used, then expire will generate a list of the files that should be removed on its standard output, and the new 
history file will be left in bistory, n, history. n. dir, and history, n.pag. This flag is useful for debugging when used with 
the-r and -s flags. N otethat if the -f flag is used, then the name specified with that flag will be used instead of history. 

If the -x flag is used, then expire will not create any new history files. This is most useful when combined with the-n, -s, 
and -t flags to see how different expiration policies would change the amount of disk space used. 

If the -z flag is used, then articles are not removed, but their names are written to the specified file. See the description of 
expire™ in news.daily(8). 

expire makes its decisions on the time the article arrived, as found in the history file. This means articles are often kept a 
little longer than with other expiration programs that base their decisions on the article's posting date. T o use the article's 
posting date, use the -p flag. Use the -w flag to "warp" time so that expire thinks it is running at some time other then the 
current time. T he value should be a signed floating-point number of the number of days to use as the offset. 



expireover 



If the -d flag is used, then the new history file and database is created in the specified directory, dir. This is useful when the 
filesystem does not have sufficient space to hold both the old and new history files. W hen this flag is used, expire leaves the 
server paused and creates a zero-length file named after the new history file, with an extension of .done to indicate that it has 
successfully completed the expiration. T hecalling script should install the new history file and unpause the server. The -r 
flag should be used with thisflag. 

If a filename is specified, it is taken as the control file and parsed according to the rules in expire. cti(5). A single dash (-) 
may be used to read the file from standard input. If no file is specified, thefile / news/lib/expire, cti is read. 

expire usually complains about articles that are posted to newsgroups not mentioned in the active file. T o suppress this 
action, use the -q flag. 

T he -v flag is used to increase the verbosity of the program, generating messages to standard output. The level should be a 
number, where higher numbers result in more output. Level one will print totals of the various actions done (not valid if a 
new history file is not written), level two will print report on each individual file and level five results in more than one line 
of output for every line processed. If the -g flag is given, then a one-line summary equivalent to the output of -vi and 
preceded bythecurrenttimewill be appended to the specified file. 

HISTORY 

W ritten by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

ctlinnd(8), dbz(3z), expire.ctl(5), history(5), innd(8), inndcomm(3) 


expireover 

expireover— Expire entries from the news overview database. 

SYNOPSIS 

expireover [ -a ][-D overvi ewdi r ][-f file ][-n ] 

[-0 overview, fmt ][-s ][-v ] [-z ][file... ] 

DESCRIPTION 

expireover expires entries from the news overview database. It reads a list of pathnames (relative to the spool directory, / 
news/spool) from the specified files or standard input if none are specified. (A filename of - may be used to specify the 
standard input.) It then removes any mention of those articles from the appropriate overview database. If the -z flag is used, 
then the input is assumed to be sorted such that all entries for a newsgroup appear together so that it can be purged at once. 
Thisflag can be useful when used with thesorted output of expire(8)'s-z flag. 

If the -s flag is used, then expireover will read the spool directory for all groups mentioned in theactive(5) file and 
remove the overview entries for any articles that do not appear. T o specify an alternate file, use the-f flag; a name of - is 
taken to mean the standard input. 

The -a flag reads the spool directory and adds any missing overview entries. It will create files if necessary. This can be used 
to initialize a database or to sync up a overview database that may be lacking articles due to a crash, overchan should be 
running, to ensure that any incoming articles get included. Using thisflag implies the -s flag; the-f flag may be used to add 
only a subset of the newsgroups. 

To see a list of the entries that would be added or deleted, use the -v flag. T o perform no real updates, use the -n flag. 

T he -d flag can be used to specify where the databases are stored. The default directory is /news/spool. 

T he-o flag may be used to specify an alternate location for the overview. fmt(5) file; this is usually only useful for debug¬ 
ging. 



Part VIII: Administration and Privileged Commands 



HISTORY 

Written by Rob Robertson (rob@vioiet.berkeiey.edu) and Rich $alz (rsaiz@uunet.uu.net) with help from Dave 
Laurence(taie@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

expire(8), overview.fmt(5) 

fastrm 

fast™— Q uickly remove a set of files. 

SYNOPSIS 

fastrm [ -d ] [ - e ] [ - uN ][-sM ] [ - cl ] basedi rectory 

DESCRIPTION 

fastrm reads a I ist of fi les, one per line, from its standard input and removes them. If a file is not an absolute pathname, it is 
taken relative to the directory specified on the command line. The base directory parameter must be a simple absolute 
pathname— that is, it must not contain any /. / or /.. / references. 

fastrm isdesigned to befasterthan thetypical | xargs rm pipeline For example, fastrm will usually chdir(2) into a 
directory before removing files from it. If theinput issorted, thismeansthat most files to be removed will be simple names. 

fastrm assumes that its input is valid and that it is safe to just do an unimk(2) call for each item to be removed. As a safety 
measure, if fastrm is run by root, it will first stat(2) the item to make sure that it is not a directory before unlinking it. 

If the-d flag is used, then no files are removed. Instead, a list of the fi les to be removed, in debug form, is printed on the 
standard output. Each line contains either the current directory of fast™ at the time it would do the unlink and then the 
pathname it would pass to uniink(2) as two fields separated by white space and a / or the absolute pathname (a single field) 
of filesit would unlink using the absolute pathname. 

If the-e flag is used, fastrm will treat an empty input file (stdin) as an error. This is most useful when fastrm is last in a 
pipeline after a preceding sort(l) because if the sort fai Is, there will usually be no output to become input of fastrm. 

If the-u flag is used, then fastrm makes further assumptions about its work environment— in particular, that there are no 
symbolic links in the target tree. This flag also suggests that it is probably faster to reference the path rather than 

start from the root and comedown (note that this probably isn't true on systems that have a namei cache, which usually 
holds everything except..). The optional n is an integer that specifies the maxi mum number of.. segments to use- paths 
that would use more than this use the absolute pathname (from the root) instead. If the-u flag is given without a value, -ui 
is assumed. 

If the -s flag is used, then fastrm will perform the unlinks from one directory—that is, when a group of files in one 
directory appear in theinput consecutively—in the order that the files appear in the directory from which they are to be 
removed. The intent of this flag is that on systems that have a per-process directory cache, finding files in the directory 
should be faster. It can have smaller benefits on other systems. The optional m is an integer that specifies the number of files 
that must be going to be removed from one directory before the files will be ordered. If the-s flag is given without a value, 
-s5 is assumed. When the directory reordering is in use, fastrm will avoid attempting to unlink files that it can't see in the 
directory, which can speed it appreciably when many of the filenames have already been removed. 

The-c flag may be given to instruct fastrm when it should chdir(2). If the number of files to be uni inked from a directory 
isat least i, then fastrm will chdir and unlink thefiles from in thedirectory. Otherwise, it will build a path relative to its 
current directory. I f -c is given without the optional integer i, then -ci isassumed, which will causefastrmto always use 
chdir. If -c is not used at all, then -c3 isassumed. Use-co to prevent fastrm from ever using chdir(2). 




fdformat 


1295 


There are also -a and -r options, which do nothing at all except allow you to say fast™ -usa, fast™ -ussr, or fast ™ 
-user. T hese happen to often be convenient sets of options to use. 

fastrm exits with a status of 0 if there were no problems or 1 if something went wrong. Attempting to remove a file that does 
not exist is not considered a problem. If the program exits with a nonzero status, it is probably a good idea to feed the list of 
filesinto an xargs rm pipeline. 

fdformat 

fdformat— Low-level formats a floppy disk. 

SYNOPSIS 

fdformat [ -n ] device 

DESCRIPTION 

fdformat does a I ow-level format on a floppy disk, device is usually one of the following (for floppy devices, the major is 2 , 
and the minor is shown for informational purposes only): 

/ dev/fdBd360 (minor =4) 

/ dev/fdohi 200 (minor =8) 

/ dev/fd0D36o (minor =12) 

/ dev/fd0H36o (minor =12) 

/ dev/fd0D72o (minor =16) 

/ dev/fdBH72B (minor =16) 

/ dev/fd0h36B (minor =20) 

/ dev/fd@h720 (minor =24) 

/ dev/fdom 440 (minor = 28 ) 

/dev/fdid360 (minor =5) 

/ dev/fdi hi 200 (minor =9) 

/ dev/fdi D36o (minor =13) 

/ dev/fdi H360 (minor =13) 

/dev/fdiD720 (minor =17) 

/dev/fdi H720 (minor = 17 ) 

/ dev/fdi h360 (minor =21) 

/ dev/fdi h720 (minor =25) 

/ dev/fdi hi 440 (minor =29) 

The generic floppy devices, /dev/fd 0 and /dev/fdi, will fail to work with fdformat when a non-standard format is being 
used or if the format has not been autodetected earlier. In this case, usesetfdprm(8) to load the disk parameters. 

OPTIONS 

-n No verify. This option will disablethe verification that is performed after the format. 

SEE ALSO 

fd(4), setfdprm(8), mkfs(8), emkfs(8) 
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AUTHOR 

Wemer Almesberger (almesber@nessie.cs.id.ethz.ch) 


Linux 0.99,1 February 1993 


fdisk 

tdisk— Partition table manipulator for Linux. 

SYNOPSIS 

fdisk [ -1 ] [ -v ] [ -s partition] [ device ] 

DESCRIPTION 

fdisk is a menu-driven program for manipulation of the hard disk partition table. The device is usually one of the following: 

/dev/hda 

/dev/hdb 

/dev/sda 

/dev/sdb 

T he partition is a device name followed byapartition number. For example /dev/hdai is the fi rst partition on thefirst hard 
disk in the system. 

If possible, fdisk will obtain the disk geometry automatically. This is not necessarily the physical disk geometry but is the 
disk geometry that M S-D OS uses for the partition table If fdisk warns you that you need to set the disk geometry, please 
believe this statement and set the geometry. This should only be necessary with certain SCSI host adapters (the drivers for 
which are rapidly being modified to provide geometry information automatically). 

Whenever a partition table is printed, a consistency check is performed on the partition table entries. This check verifies that 
the physical and logical start and end points are identical and that the partition starts and ends on a cylinder boundary 
(except for the first partition). 

Old versions of fdisk (all versions prior to l.lr including 0.93) incorrectly mapped the cylinder/head/sectdr specification 
onto absolute sectors. This might result in thefirst partition on a drive failing the consistency check. If you use LI LO to 
boot, this situation can be ignored. H owever, there are reports that the OS/2 boot manager will not boot a partition with 
inconsistent data. 

Some versions of M S-D OS create a first partition that does not begin on a cylinder boundary but on sector 2 of thefirst 
cylinder. Partitions beginning in cylinder 1 cannot begin on a cylinder boundary, but this is unlikely to cause difficulty 
unless you have OS/2 on your machine. 

In version l.lr, a blkrrpart ioctio isperformed before exiting when thepartition table is updated. Thisisprimarily to 
ensure that removable SC SI disks have their partition table information updated. If the kernel does not update its partition 
table information, fdisk warns you to reboot. If you do not reboot your system after receiving such a warning, you might 
lose or corrupt the data on the disk. Sometimes blkrrpart fails silently; when installing Linux, you should always reboot 
after editing the partition table 

DOS 6JY WARNING 

TheDOS 6.x format command looks for some information in thefirst sector of the data area of the partition and treats this 
information as more reliable than the information in thepartition table, dos format expects DOS fdisk to clear thefirst 
512 bytes of the data area of a partition whenever a size change occurs, dos format will look at this extra information even if 
the /u flag isgiven 
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We consider this a bug in dos format and dos fdisk. 

The bottom line is that if you use cf disk or fdisk to change the size of a DOS partition table entry, then you must also use 
dd to zero the first 512 bytes of that partition before using dos format to format the partition. For example if you were 
using ctdisk to make a DOS partition table entry for /dev/hdai, then (after exiting fdisk or cf disk and rebooting Linux 
so thatthepartition table information isvalid) you would usethecommand dd if=/dev/zero of=/dev/hdai bs=5i2 
count=i to zero the first 512 bytes of the partition. 

Be extremely careful if you use the dd command because a small typo can make all of the data on your disk useless. 

For best results, you should always use an OS-specific partition tableprogram. For example, you should makeDOS 
partitions with the dos fdisk program and Linux partitions with the Linux fdisk or Linux cf disk program. 

OPTIONS 

-V 
-1 

-s partition 


BUGS 

Although this man page (written by faith@cs.unc.edu) is poor, there is excel lent documentation in the readme, fdisk file 
(written byLeBianc@mcc.ac.uk) that should always be with the fdisk distribution. If you cannot find this file in theutii- 
linux-* directory or with the f disk, c source file then you should write to the distributor of your version of fdisk and 
complain that you do not have all of the available documentation. 

AUTHOR 

A.V. LeBlane (LeBianc@mcc.ac.uk). vl.Or: SCSI and extfs support added by Rik Faith (faith@cs.unc.edu). vl.lr: Bug 
fixes and enhancements by Rik Faith (faith@cs.unc.edu), with special thanks to M ichael Bischoff (n041905@ws.rz. tu¬ 
bs. de or mbi@mo.math.nat.tu-bs.de). vl.3: Latest enhancements and bug fixes by A.V. LeB lane, including the addition 
of the -s option. v2.0: D isks larger than 2GB are now fully supported, thanks to Remy Card's nseek support. 

Linux 1.0, 3 Junel995 


Prints version number of fdisk program. 

Lists the partition tables for /dev/hda, /dev/hdb, /dev/sda, /dev/sdb, /dev/sdc, / 
dev/sdd, /dev/sde, /dev/sdf, /dev/sdg, and /dev/sdh and then exits. 

If the parti ti on is not a D 0 S partition (the partition ID is greater than 10), then the 
size of that partition isprinted on thestandard output. Thisvalue is usually used as 
an argument to themkfs(8) program to specify the size of the partition that will be 
formatted. 


filechan 

filechan— File-writing back end for InterN etN ews. 

SYNOPSIS 

filechan [ -d directory ] [ - f fields ][-m mapfile ] [ - p pi df i I e ] 

DESCRIPTION 

filechan reads li nes from standard input and copies certain fields in each line into files named by other fields within the 
line, filechan is intended to be called by innd( 8 ) as a channel feed. (It is not a full exploder and does not accept commands; 
see newsf eeds( 5 ) for a description of the difference and buffchan( 8 ) for an exploder program.) 

filechan input is interpreted as a set of lines. Each line contains a fixed number of initial fields, followed by a variable 
number of filename fields. All fields in a line are separated by whitespace. The default number of initial fields is one; the-f 
flag may be used to specify a different number of fields. 
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For each line of input, tiiechan writes the initial fields, separated by whitespace and followed by a newline, to each of the 
files named in the filename fields. W hen writing to a file, tiiechan opens it in append mode and tries to lock it and change 
the ownership to the user and group who owns the directory where the file is being written. 

By default, tiiechan writes its arguments into the directory /news/spool/out. going. T he -d flag may be used to specify a 
directory the program should change to before starting. 

If the-p flag is used, the program will write a line containing its process ID (in text) to the specified file. 

If tiiechan is invoked with -t 2 and given the following input: 

news/software/b/132 <1643@munnari.oz.au>foo uunet 
news/software/b/133 <102060@litchi.foo.com> uunet munnari 
comp/sources/unix/2002 <999@news.foo.com>foo uunet munnari 

Then thefiletoo will have these lines: 

news/software/b/132 <1643@munnari.oz.au> 
comp/sources/unix/2002 <999@news.foo.com> 

T he file munnari will have these I i nes: 

news/software/b/133 <102060@litchi.foo.com> 
comp/sources/unix/2002 <999@news.foo.com> 

Thefileuunet will have these lines: 

news/software/b/132 <1643@munnari.oz.au> 
news/software/b/133 <102060@litchi.foo.com> 
comp/sources/unix/2002 <999@news.foo.com> 

Because the time window in which a file is open is very small, complicated flushing and locking protocols are not needed; a 
mv(l) followed by asieep(l) for a couple of seconds is sufficient. 

A map file may be specified by using the-m flag. Blank lines and lines starting with anumbersign (#) areignored. All other 
lines should have two hostnames separated by a colon. The first field is the name that may appear in the input stream; the 
second field names the file to be used when the name in the first field appears. For example, the foil owing map file may be 
used to map the short names to the full domain names: 

# This is a comment uunet:news.uu.net foo:foo.com munnari:munnari.oz.au 

HISTORY 

W ritten by Robert Elz (kre@munnari.oz.au); flags added by Rich $alz (rsalz@uunet.uu.net). 

SEE ALSO 

buffchan(8), innd(8), newsfeeds(5) 

fsck 

tsck— Check and repair a Linux filesystem. 

SYNOPSIS 

fsck [ -AVRTN ][-s ][-t fstype ][fs-options ] filesys [ ... ] 
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DESCRIPTION 

fsck is used to check and optionally repair a Linux filesystem, fiiesys is either the device name (such as/dev/hdai or / dev/ 
sdb 2 ) or the mount point (such as / , /usr, or /home) for the filesystem. If this fsck has several filesystems on different 
physical disk drives to check, this fsck will try to run them in parallel. This reduces the total amount time it takes to check 
all of the filesystems because fsck takes advantage of the parallelism of multiple disk spindles. 

The exit code returned by fsck isthesum of the following conditions: 

0 No errors 

1 Filesystem errors corrected 

2 System should be rebooted 

4 Filesystem errors left uncorrected 

8 0 perational error 

16 U sage or syntax error 

128 Shared library error 

The exit code returned when all filesystems are checked using the - a option is the bitwise or of the exit codes for each file 
system that is checked. 

In actuality, fsck is simply a front end for the various filesystem checkers (fsck. fstype) available under Linux. The 
filesystem-specific checker issearched for in /sbin first, then in /etc/fs and /etc, and finally in the directories listed in the 
path environment variable. Please see the filesystem-specific checker manual pages for further details 


OPTIONS 

-A 


-T 

-N 


-S 


-V 

-tfstype 


fs-options 


Walk through the /etc/fstab file and try to check all filesystems in one run. This 
option istypically used from the /etc/rc system initialization file instead of 
multiple commands for checking a single file system. 

When checking all filesystems with the -a flag, skipthe root filesystem (in caseit's 
already mounted read-write). 

Don't show thetitleon startup. 

D on't execute; just show what would be done 

Serialize fsck operations. This is a good idea if you checking multi pie filesystems in 
and the checkers are in an interactive mode. (N ote e 2 fsck runs in an interactive 
mode by default. T o makee 2 fsck run in a non-interactivemode, you must either 
specify the -p or -a option, if you want errorsto be corrected automatically, or the - 
n option if you do not.) 

Produce verbose output, including all filesystem-specific commands that are 
executed. 

Specifies the typeof filesystem to be checked. When the -a flag is specified, only 
filesystems that match fstype are checked. If fstype is prefixed with no, only 
filesystems whose filesystem do not match fstype are checked. 

Usually, the filesystem type is deduced by searching for f i i esys in the / etc/fstab 
file and using the corresponding entry. If the type can not be deduced, fsck will use 
the type specified by the -t option if it specifies a unique filesystem type. If this type 
is not available, the the default filesystem type (currently ext 2 ) is used. 

Any options that are not understood by fsck, or that follow the - option are treated 
as filesystem-specific optionsto be passed to the filesystem-specific checker. 
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Currently, standardized filesystem-specific options are somewhat in flux. Although not guaranteed, thefollowing options are 
supported by most filesystem checkers: 

-a Automatically repair the fi lesystem without any questions (Use this option with caution.) Note 

that e 2 fsck supports -a for backwards compatibility only. This option is mapped to e 2 fsck's -p 
option, which is safe to use, unlike the -a option that most filesystem checkers support. 

-r Interactively repair the fi lesystem (ask for confirmations). Note: It is generally a bad idea to use 

thisoption if multi pletsck’sare run in parallel. Also note that this is e 2 f sck default behavior; it 
supports thisoption for backwards compatibility reasonsonly. 

AUTHOR 

TheodoreTs'o (tytso@mit.edu) 

The manual page was shamelessly adapted from David Engel and Fred van Kern pen's generic tsck front-end program, which 
in turn was shamelessly adapted from Remy Card's version for the ext 2 filesystem. 

FILES 

/etc/fstab 


SEE ALSO 

fstab(5), mkfs(8), fsck.minix(8), fsck.ext2(8) Of e2fsck( 8), fsck.xiafs(8) 


Verson 0.5b, N ovember 1994 


fsck.minix 

tsck.minix—A filesystem consistency checker for Linux. 

SYNOPSIS 

fsck.minix [ -larvsmf ] device 

DESCRIPTION 

tsck.minix performs a consistency check for the Linux MINIX filesystem. The current version supports the 14 character and 
30 character filename options. 

The program assumes the filesystem is quiescent, tsck.minix should not be used on a mounted device unless you can be sure 
nobody is writing to it (and remember that the kernel can write to it when it searches for files). 

T he device wi II usually have thefollowing form: 

/dev/hda[1-8] 

/dev/hdb[1-8] 

/dev/sda[1-8] 

/dev/sdb[ 1 -8] 

If the filesystem was changed (that is, repaired), then tsck.minix will print File system has changed and will sync(2) three 
times before exiting. Because Linux does not currently have raw devices, there is no need to reboot at this time (versus a 
system that does have raw devices). 

WARNING 

tsck.minix should not be used on a mounted filesystem. Using tsck.minix on a mounted filesystem is very dangerous due to 
the possibility that deleted files are still in use and can seriously damage a perfectly good filesystem! If you absolutely have to 
run tsck.minix on a mounted filesystem (that is, the root filesystem), make sure nothing is writing to the disk and that no 
fi les are "zombies" waiting for deletion. 
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OPTIONS 

-i Lists all filenames. 

-r Performsinteractiverepairs 

-a Performsautomatic repairs (this option implies -r) and serves to answer all of the questions asked with the 

default. N ote that this can be extremely dangerous in the case of extensive filesystem damage. 

-v Verbose. 

-s Outputs super-block information. 

-m ActivatesM IN IX-like"modenot cleared" warnings. 

-f Force filesystem check even if the filesystem was marked as valid. (This marking is done by the kernel 

when thefilesystem isunmounted.) 

SEE ALSO 

fsck(8), fsck.ext(8), fsck.ext2(8), fsck.xiafs(8), mkfs(8), mkfs.minix(8), mkfs.ext(8), mkfs.ext2(8), mkfs.xiafs(8), reboot(8) 

DIAGNOSTICS 

There are numerous diagnostic messages. The ones mentioned here are the most commonly seen in normal usage. 

If the device does not exist, fsck.minix will print unable to read super block. If the device exists but is not a M INIX 
filesystem, fsck.minix will print Bad magic number in super-block. 

EXIT CODES 

The exit code returned by fsck.minix isthesum of the following: 

0 No errors 

3 Filesystem errors corrected; system should be rebooted if filesystem was mounted. 

4 Filesystem errors left uncorrected. 

8 Operational error. 

is U sage or syntax error. 

In point of fact, only 0 , 3 , 4 , 7 ,8, and 16 can ever be returned. 

AUTHOR 

LinusTorvalds (tonvaids@cs.heisinki.fi). Error codevalues by Rik Faith (faith@cs.unc.edu). Added support for filesystem 
valid flag: Dr. Wettstein (greg%wind. uucp@piains.nodak.edu). C heck to prevent fsck of mounted filesystem added by Daniel 
Quinlan (quinlan@yggdrasil.com). 

Linux 0.99,10 January 1994 
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ftpd— D ARPA Internet FileTransfer Protocol server. 

SYNOPSIS 

ftpd [ - d] [ -1] [ -1 t i me 0 u t ] [-T maxtimeout] 

DESCRIPTION 

ftpd is the D ARPA Internet FileT ransfer Protocol server process. The server usestheTCP protocol and listens at the port 
specified in the FTP service specification; seeservices(5). 
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Available options: 

-d 

Debugging information is written to the syslog. 

-1 

Each FTP 1 session islogged in the syslog. 

-t 

The inactivity timeout period is set to timeout seconds. (The default is 15 minutes.) 

-T 

A client can also request a different timeout period; the maxi mum period allowed can beset to timeout 
seconds with the -t option. The default limit is 2 hours. 

The FTP server currently supports the following FTP requests; case is not distinguished. 

Request 

Description 

ABOR 

Abort previous command 

ACCT 

Specify account (ignored) 

ALLO 

Allocate storage (vacuously) 

APPE 

Append to a file 

CDUP 

C hangeto parent of current working directory 

CWD 

C hangeworking directory 

DELE 

Delete a file 

HELP 

Give help information 

LIST 

G ive list files in a directory (" is -igA ") 

MKD 

M ake a directory 

MDTM 

Show last modification timeof file 

MODE 

Specify data transfer mode 

NLST 

Give name list of filesin directory 

NOOP 

Do nothing 

PASS 

Specify password 

PASV 

P repare for server-to-server transfer 

PORT 

Specify data connection port 

PWD 

Print the current working directory 

QUIT 

T erminate session 

REST 

Restart incomplete transfer 

RETR 

Retrieve a file 

RMD 

Remove a directory 

RNFR 

Specify rename-from filename 

RNTO 

Specify rename-to filename 

SITE 

N onstandard commands (see next section) 

SIZE 

Return size of file 

STAT 

Return status of server 

STOR 

Store a file 

STOU 

Storeafilewith a unique name 

STRU 

Specify data transfer structure 

SYST 

show operating system type of server system 

TYPE 

specify data transfer type 

USER 

specify username 

XCUP 

change to parent of current working directory (deprecated) 




Request Description 

xcwd changeworking directory (deprecated) 

xmkd makea directory (deprecated) 

xpwd print the current working directory (deprecated) 

xrmd remove a directory (deprecated) 

The following non-standard or U N IX-specific commands are supported by thesiTE request: 


Request 

D escription 

Example 

UMASK 

Change umask 

SITE UMASK 002 

IDLE 

Set idletimer 

SITE IDLE 60 

CHMOD 

Change mode of a file 

SITE CHMOD 755 

HELP 

Give help information 

SITE HELP 


The remaining FTP requests specified in Internet RFC 959 are recognized but not implemented, mdtm and size are not 
specified in RFC 959 but will appear in the next updated FTP RFC. 

The FTP server will abort an active file transfer only when theABOR command is preceded by aT el net "Interrupt Process" 
(IP) signal and a Telnet "Synch” signal in the command T el net stream, as described in Internet RFC 959. If asTAT 
command is received during a data transfer, preceded by a Tel net IP and synch, transfer status will be returned. 

ftpd interprets filenames according to the globbing conventions used by csh(l). This allows users to utilize the 
metacharacters Li &*?[]. 

ftpd authenticates users according to four rules: 

The username must be in the password database and not have a null password. In this case, a password must be provided 
by the client before any file operations may be performed. 

The username must not appear in the file (see ttpusers(5)). 

Theuser must havea standard shell returned by getusersheii(3). 

If the username is anonymous or FTP, an anonymous FTP account must be present in the password file (user FTP). In 
this case, theuser is allowed to log in by specifying any password. (By convention, this is given as the client host's name.) 

In the last case, ftpd takes special measures to restrict the client's access privileges. T he server performs a chroot(2) command 
to the home directory of the FT P user. So that system security is not breached, it is recommended that the FT P subtree be 
constructed with care; the following rules are recommended: 

‘ftp M akethehomedirectory owned by root and unwritable by anyone. 

■ftp/bin M ake this directory owned by root and unwritable by anyone The program is(l) must be present to 

support the list command. This program should have mode in. 

■ftp/etc M ake this directory owned by root and unwritable by anyone The files passwd(5) and group(5) must be 

present for the is command to be able to produce owner names rather than numbers. The password field 
in passwd is not used and should not contain real encrypted passwords. These files should be mode 444 and 
owned by root. Don't use the system's /etc/passwd file as the password file or the system's /etc/group file 
as the group file in the ‘ftp/etc directory. 

Pa ‘ftp/pub M ake this directory mode 755 and owned by root. Create a subdirectory in ‘ftp/pub with the appropriate 
mode(777 or 733 ) if you wantto allow normal users to upload files. 

SEE ALSO 

ftp(l), getusershell(3), ftpusers(5), syslogd(8) 

BUGS 

The anonymous account isinherently dangerous and should avoided when possible. 
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The server must run as the super-user to create sockets with privileged port numbers. It maintains an effective user ID of the 
logged-in user, reverting to the super-user only when binding addresses to sockets. The possible security holes have been 
extensively scrutinized but are possibly incomplete. 

HISTORY 

The command appeared in BSD 4.2. 

BSD 4.2,16 March 1991 


ifconfig 

ifconfig — C onfigure a network interface. 

SYNOPSIS 

ifconfig [interface] 

ifconfig interface [aftype] options | address ... 

DESCRIPTION 

ifconfig is used to setup (and maintain thereafter) the kernel-resident network interfaces. It is used at boot time to configure 
most of them to a running state. After that, it is usually only needed when debugging or when system tuning is needed. 

If no arguments are given, ifconfig just displays the statusof the currently defined interfaces. If the single interface argument 
is given, it displays the status of the given interface only. Otherwise, it assumes that things have to be set up. 

ADDRESS FAMILIES 

If the first argument after the interface name is recognized as the name of a supported address family, that address family is 
used for decoding and displaying all protocol addresses. Currently supported address families include inet (TCP/IP, default) 
and ax25 (AM PR Packet Radio.) 

OPTIONS 


interface 

The name of theN ET interface. This usually is a name such aswd 0 , si3, or something like that: 
a devicedriver namefollowed by a unit number. 

up 

This flag causes the interface to be activated. It isimplicitly specified if the i nterface is given a 
new address (see below). 

down 

This flag causes the driver for this interface to be shut down and is useful when things start 
going wrong. 

Harp 

Enable or disable the use of theARP protocol on this interface. If theminus(-) sign ispresent, 
theflag isturned OFF. 

[-]trailers 

E nable or di sable the use of trai lers on Ethernet frames. T his is not used i n the current 
implementation of N ET. 

[-]allmulti 

Enableor disablethepromiscuous modeof the interface. This meansthat all incoming frames 
get sent to the network layer of the system kernel, allowing for networking monitoring. 

metric N 

This parameter sets the interface metric. It is not used at present, but we implement it for the 
future. 

mtu N 

This parameter sets the M aximum T ransfer Unit (MTU) of an interface. For Ethernet, this is a 
number in the range of 1000-2000 (default is 1500 ). For SLIP, use something between 200 and 
4096. N ote that the current implementation does not handle IP fragmentation yet, so you'd 
better make the MTU large enough! 

dstaddr addr 

Set the "other end's” IP address in case of a point-to-point link, such as PPP. This keyword is 
obsoleted by the new pointopoint keyword. 
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netmask addr 


[-]broadcast [addr] 


[-lpointopoint [addr] 


hw 


address 


FILES 

/dev/net/socket 


Set the IP network mask for this interface. This value defaults to the usual class A, B, or C 
network mask (as deducted from the interface IP address), but it can beset to any value for the 
use of subnetting. 

If the address argument is also given, set the protocol broadcast address for this interface. 
Otherwise, it only sets the iff_broadcast flag of the interface. If the keyword was preceded by a 
minus(-) sign, then theflag iscleared instead. 

This keyword enables the point- to -point mode of an interface, meaning that it is a direct link 
between two machines with nobody else listening on it. (At least we hope that this isthe case, 
grin :-).) 

If the address argument is also given, set the protocol address of the other side of the link, just 
like the obsolete dstaddr keyword does. Otherwise, it only sets the iff pointopoint flag of the 
interface. If the keyword was preceded byaminus(-) sign, then theflag iscleared instead. 

Set the hardware address of this interface if the device driver supports this operation. T he 
keyword must be followed by the name of the hardware class and the printable ASC11 
equivalent of the hardware address. H ardware classes currently supported include ether 
(Ethernet), ax25 (AM PR AX.25), and ppp, although the latter is not really supported yet. 

The hostname or IP address (a hostname will be resolved into an IP address) of that interface. 
This parameter is required, although the syntax doesn't currently require it. 


BUGS 

N one so far, although the syntax checking could be better. 

AUTHOR 

Fred N . van Kernpen (waltje@uwalt.nl.nugnet.org) 

6 October 1993 


inetd 

inetd— I nternet superserver. 

SYNOPSIS 

inetd [ -d] [configuration file] 

DESCRIPTION 

inetd should be run at boot time by /etc/rc.local (see rc(8)). It then listens for connections on certain I nternet sockets. 
When a connection is found on one of its sockets, it decides what service the socket corresponds to and invokes a program to 
service the request. After the program isfinished, it continues to listen on the socket (except in somecases, which are 
described later). Essentially, inetd allows running onedaemon to i nvoke several others, reducing load on the system. 

The option available for inetd: 

-d Turns on debugging. 

Upon execution, inetd reads its configuration information from a configuration file, which, by default, is/etc/inetd.cont. 
There must bean entry for each field of the configuration file, with entries for each field separated by a tab or a space. 
Comments are denoted by a# at the beginning of a line. There must bean entry for each field. The fields of the configura¬ 
tion file are as follows: 
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service name 
socket type 
protocol 

wait/nowait[.max] 
user[.group] 
server program 
server program arguments 

T o specify an Sun-RPC based service, theentry would contain these fields: 
service name/version 
socket type 
rpc/protocol 
wait/nowait[.max] 
user[.group] 
server program 
server program arguments 

The service-name entry isthenameof a valid servicein thefile /etc/services . For internal services, the service name must 
be the official name of the service (that is, the first entry in /etc/services). W hen used to specify a Sun-RPC based service, 
this field is a valid RPC service name in thefile /etc/rpc. The part on the right of the / is the RPC version number. This can 
simply be a single numeric argument or a range of versions. A range is bounded by the low version to the high version 
- rusers/1-3. 

The socket type should be one of stream, dgram, raw, rdm, or seqpacket, depending on whether the socket is a stream, 
datagram, raw, reliably delivered message, or sequenced packet socket. 

The protocol must be a valid protocol as given in /etc/protocois. Examples might be tcp or udp. Rpc-based services are 
specified with the rpc/tcp or rpc/udp servicetype. 

Thewaitynowait entry is applicable to datagram sockets only. (Other sockets should have a nowait entry in this space.) If a 
datagram server connects to its peer, freeing the socket so inetd can receive further messages on the socket, it is said to be a 
multithreaded server and should use the nowait entry. For datagram servers that process all incoming datagrams on a socket 
and eventually timeout, the server is said to be single-threaded and should use a wait entry. comsat(8), biff (1), and taikd(8) 
are examples of the latter type of datagram server. Tftpd(8) is an exception; it is a datagram server that establishes pseudo¬ 
connections. 

It must be listed as wait in order to avoid a race; the server reads the first packet, creates a new socket, and then forks and 
exits to allow inetd to check for new service requests to spawn new servers. The optional max suffix (separated from wait or 
nowait by a dot) specifies the maximum number of server instances that may be spawned from inetd within an interval of 60 
seconds. W hen omitted, max defaults to 40 . 

Theuser entry should contain the username of the user as whom theserver should run. This allows for servers to be given 
less permission than root. An optional group name can be specified by appending a dot to the username followed by the 
group name. This allows for servers to run with a different (primary) group ID than specified in the password file If a group 
is specified and theuser is not root, the supplementary groups associated with that user will still beset. 

The server-program entry should contain the pathname of the program that isto be executed by inetd when a request is 
found on its socket. If inetd provides this service internally, this entry should be internal. 

Theserver program arguments should appear just as arguments normally do, starting with argv [@], which isthenameof the 
program. If the service is provided internally, theword internal should take the place of this entry. 

inetd provides several trivial services in tern ally by useof routines within itself. These services are echo, discard, chargen 
(character generator), daytime (human readable time), and time (machine readable time in the form of the number of seconds 
since midnight, J anuary 1,1900). All of these services areT CP based. For details of these services, consult the appropriate 
RFC from the N etwork Information Center. 
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metd rereads its configuration file when it receives a hangup signal, sighup. Services may be added, deleted, or modified 
when the configuration file is reread, metd creates a file /etc/metd. pi d that contains its process identifier. 

SEE ALSO 

comsat(8), fingerd(8), ftpd(8), rexecd(8), rlogind(8), rshd(8), telnetd(8), tftpd(8) 

HISTORY 

The command appeared in BSD 4.3. Support for Sun-RPC based services is modeled after that provided by Sun-OS 4.1. 

BSD 4.3,16 March 1991 


init, telinit 

init, telinit— Process control initialization. 

SYNOPSIS 

/sbin/init [ -t sec ][0123456SsQq ] 

/sbin/telinit [ -t sec ][0123456sSQqabc ] 

DESCRIPTION 

init 

init is the father of all processes. Its primary role is to create processes from a script stored in the file /etc/mittab (see 
mittab(5)). This file usually has entries that cause mit to spawn gettys on each line that users can log in. It also controls 
autonomous processes requi red by any particular system. 

A run level is a software configuration of the system that allows only a selected group of processes to exist. The processes 
spawned by init for each of these run levelsare defined in the /etc/mittab file, init can be in oneof eight run levels, 06 and 
s or s. The run level is changed by having a privileged user run /sbm/teimit, which sends appropriate signals to init, telling 
it which run level to change to. 

After init is invoked as the last step of the kernel booting, it looks for the file /etc/mittab to see if there is an entry of the 
type mitdetauit (see inittab(5)). mitdefauit determi nes the initial run level of the system. If there is no such entry or no 
/etc/mittab at all, a run level must be entered at the system console. 

Run level s or s brings the system to single-user mode and does not requi re an /etc/mitttab file. In singleuser mode, 

/bin/sh is invoked On /dev/console. 

/dev/consoie need not necessarily be the physical system console. W hen mit is told to enter singleuser mode or run level 1 
(either directly, by init s, or by telling shutdown to enter maintenance mode), it will link the terminal line the command 
was executed from to /dev/consoie. The device /dev/systty is cal led the physical system console and the device /dev/consoie 
is called the logical system console. If thelogical system console is not the physical system console, pressing the combination 
C trl+Alt+D el on the physical system console will forcea relink of /dev/consoie to /dev/systty. A terminal linecan only 
become the logical console if it's listed in the file /etc/securetty. All this is in preparation of the day that the Linux kernel 
will support serial consoles. 

Beware: If you want to run x or anything else that is aware of Virtual Consoles, thelogical system console (/dev/consoie) 
needsto be the same as the physical system console (/dev/systty). 

When entering single-user mode, init reads the console's iocti(2) states from /etc/iocti.save. If this file does not exist, init 
initializes the line at 9600 baud and with clocal settings. When mit leaves single-user mode, it stores the console's iocti 
settings in thisfile so it can re-use them for the next single-user session. If thelogical system console is changed to another 
terminal line the settings of the linefrom which themu or telinit command was given are stored in /etc/iocti.save too, 
so that the terminal linewill be initialized correctly in single-user mode. 
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When entering a multi-user mode the first time, init performs the boot and bootwait entries to allow filesystems to be 
mounted before users can log in. Then all entries matching the run level are processed. 

Each time a chi Id terminates, init records the fact and the reason it died in /etc/utmp and /var/adm/wtmp if these files exist. 

After it has spawned all the processes specified, init waits for one of its descendant processes to die, a powerfail signal, or a 
signal by /sbin/teiinit to change the system's run level. W hen one of these three conditions occurs, it re-examines the 
/etc/inittab file N ew entries can be added to thisfileat anytime. However, init still waits for one of the three conditions 
to occur. T o provide for an instantaneous response the q or q command can wake up init to reexamine the /etc/inittab 
file. 

If init is not in singleuser mode and receives a powerfail signal, special powerfail entries are invoked. 

When init is requested to change the run level, it sends the warning signal sigterm to all processes that are undefined in the 
new run level. It then waits 20 seconds before forcibly terminating these processes viathekill signal sigkill. 

N otethat init assumes that all these processes (and their descendants) remain in the same process group that init originally 
created for them. If any process changes its process group affiliation, it will not receive these signals. Such processes need to 
determinated separately. 

telinit 

/sbin/teiinit is I inked to /sbin/init. It takes a one-character argument and signals init to perform the appropriate action. 

T he following arguments serve as directives to /sbin/teiinit: 

0 , i, 2 , 3 , 4 , 5 , or 6 T ell /sbin/init to switch to the specified run level. 

a, b, c Tell /sbin/init to process only those /etc/inittab file entries having run level a, b, ore. 

q or q Tell /sbin/init to re-examinethe /etc/inittab file, 

s or s Tell /sbin/init to switch to single-user mode. 

/sbin/teiinit can also tell init how much time it should wait between sending processes the term and the kill signal; the 
default is 20 seconds, but it can be changed by the -t sec option. 

/sbin/teiinit can be invoked only by users with appropriate privileges. 

RUN LEVELS 

Run levels 0 , 1 , and 6 are reserved. Run level 0 isused to halt the system, run level 6 isused to reboot the system, and run 
level 1 isused to getthesystem down into single-user mode. Run level s isnot really meantto be used directly but should be 
used by scripts that are executed when entering run level 1 . For more information on this, see the man pages for shutdown(l) 
and inittab(5). 

FILES 

/etc/inittab 

/dev/console 

/dev/systty 

/etc/ioctl.save 

/etc/utmp 

/var/adm/wtmp 

CONFORMING TO 

init is compatible with the System V init. The scripts that are used with it, however, are mostly modeled after the BSD 
startup scripts. There are startup scripts avail able that let Linux boot more like a System V system, but most people find 
them too complex. 

WARNINGS 

init assumes that processes and descendants of processes remain in the same process group that was originally created for 
them. If the processes change their group, init can't kill them and you might end up with two processes reading from one 
terminal line. 
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DIAGNOSTICS 

If /sbin/init finds that it is continuously respawning an entry more than ten times in two minutes, it will assume that there 
is an error in the command string, generate an error message on the system console, and refuse to respawn this entry until 
either five minutes has elapsed or it receives a signal. This prevents it from eating up system resources when someone makes a 
typographical error in the/etc/imttab file or the program for the entry is removed. 

AUTHOR 

M iquel van Smoorenburg (miqueis@drinkei.ni.mugnet.org); initial manual page by M ichael H aardt 
(u31b3hs@pool.informatik.rwth-aachen.de). 

SEE ALSO 

getty(l), login(l), sh(l), who(l), shutdown(l), kill(2), inittab(5), utmp(5) 

19 January 1994 
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innd, inndstart— InterN etN ews daemon. 

SYNOPSIS 

innd [ -a ][-c days ][-d ][-f ][-i count ] [-o count ] [ -1 size ] 

[ - m mode ] [ - n flag ] [ - p port ][-r ][-s ][-S host ][-t timeout ] [ - u ] [ - x ] 
inndstart [flags ] 

DESCRIPTION 

innd, the I nterN etN ews daemon, handles all incoming N NTP feeds. It reads the active(5), newsfeeds(5), and hosts. nntp(5) 
files into memory. It then opens the N NTP port to receive articles from remote sites, a U N IX-domain stream socket to 
receive articles from local processes such asnnrpd(8) and rnews(l), and all N IX-domain datagram socket for use by 
ctiinnd(8) to di rect the server to perform certain actions. It also opens the history(5) database and two log files to replace its 
standard output and standard error. If the -p flag isused, then the N NTP port is assumed to be open on the specified 
descriptor. (If thisflag isused, then innd assumes it is running with the proper permissions and it does not call chown(2) on 
any f i I es o r d i rectori es i t creates.) 

Once the files and sockets have been opened, innd waits for connections and data to be ready on its ports by using seiect(2) 
and non-blocking I/O. If no data is avail able, then it flushes its in-core data structures. The default number of seconds to 
timeout before flushing is 300 . This timeout may be changed by using the-t flag. 

T 0 limit the number of incoming N NTP connections, use the-i flag. A valueof 0 suppresses this check. 

T 0 limit the number of files that are kept open for outgoing file feeds, use the -0 flag. The default is the number of available 
descriptorsminussomereserved for internal use. 

T 0 limit the size of an article, use the -1 flag. If thisflag isused, then any article bigger than size bytes is rejected. The 
default is no checking, which can also be obtained by using a valueof 0 . 

mnd rejects articles that are too old. Although this behavior can be controlled by the history database, occasionally a site 
dumps a batch of very old news back onto the network. Use the -c flag to specify a cutoff. For example -021 rejects any 
articles that were posted more than 21 days ago. A valueof 0 suppresses this check. 

innd usually puts itself into the background, sets its standard output and error to log files, and disassociates itself from the 
terminal. Using the -d flag instructs the server to not do this, whereas using the -f flag just leaves the server running the 
foreground. The logs are usually buffered; usethe-u flag to have them unbuffered. 

T 0 start the server in a paused or throttled state (see ctiinnd(8)) use the -m flag to set the initial running mode. The 
argument should start with a single letter g, p, or t to emulate the go, pause, or throttle commands. 
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If the -r flag is used, the server renumbers the active file as if a renumber command were sent. 

If the -s flag is used, then innd does not do any work but instead just checks the syntax of the news-feeds file. It exits with an 
error status if there are any errors; the actual errors are reported in sysiog(3). 

If innd gets an NOSPC error (see intro(2)) while trying to write the active file, an article file, or the history database, it sends 
itself a throttle command. T his also happens if it gets too many I/O errors while writing to any files. 

Any subprocesses spawned by the server get anice(2) value of 10 . 

The-n flag specifies whether pausing or throttling the server should also disable future news-reading processes. A value of y 
makes news readers act as the server, a value of n allows news reading even when the server is not running. 

If the -s flag is used, then innd runs in slave mode. W hen running as a slave, the server only accepts articles from the 
specified host, which must usethexrepiic protocol extension. N otethat either the host must appear in the hosts.nntp file or 
the server must be started with the -a flag. 

By default, if a host is not mentioned in the hosts, nntp file then the connection is handed off to nnrpd. If the -a flag is used, 
then any host can connect and transfer articles. 

If the-xflag isused, then aXref header isadded to all articles even if they are not cross-posted. 

inndstart is a small front-end program that opens the N NTP port, sets its user ID and group ID to the news maintained 
and then executes innd with the-p flag and a minimal secure environment. This is a small, easily understood front-end 
program that can be used if a site does not want to run innd with root privileges. 

CONTROL MESSAGES 

Arriving articles that have a Control header or have a Subject header that starts with the five characters cmsg are called control 
messages. Except for the cancel message, these messages are implemented by external programs in the /news/bin/control 
directory. (Cancel messages update the history database, so they must be handled internally; thecost of synching, locking, 
and then unlocking istoo high, given the number of cancel messages that are received.) 

When acontrol message arrives, the first word of thetext isconverted to lowercase and used asthenameof theprogram to 
execute; if the named program does not exist, then a program named default is executed. 

All control programs are invoked with four parameters. The first is the address of the person who posted the message; this is 
taken from the Sender header. If that header is empty, then it is taken from the From header. The second parameter is the 
address to send replies to; this is taken from the Reply-T 0 header. If that header is empty, then the poster's address isused. 
The third parameter is a name under which the article is filed, relative to the news spool directory. The fourth parameter is 
the host that sent the article, as specified on thePath line. 

The distribution of control message is also different from those of standard articles. 

Control messages are usually filed in the newsgroup named control. They can be filed in subgroups, however, based on the 
control message command. For example anewgroup message is filed in control, newgroup if that group exists, otherwise it will 
be filed in control. 

Sites may explicitly have the "control" newsgroup in their subscription list, although it is usually best to exclude it. If a 
control message is posted to a group whose name ends with the four characters .cti, then the suffix is stripped off and what 
is left isused as the group name. For example, a cancel message posted to news, admin, cti will be sent to all sites that 
subscribe to control or news, admin, newgroup and rmgroup messages receive additional special treatment. If the message is 
approved and posted to the name of the group being created or removed, then the message is sent to all sites whose 
subscription patternswould cause them to receive articles posted in that group. 

If an article is posted to a newsgroup that starts with the three letters to., it gets special treatment if the newsgroup does not 
exist in the active file. The article is filed into the newsgroup to and it is sent to the first site named after the prefix. For 
example, a posting to to.uunet isfiled in to and sent to the site uunet. 

PROTOCOL DIFFERENCES 

mnd implements the N l\l T P commands defined in RFC 977 with the following differences: 



innd, inndstart 



■ The list may be followed by an optional active, active, times, or newsgroups argument. Thiscommon extension isnot 
fully supported; see nnrpd(8). 

■ Theauthinfo user and authinfo pass commands are implemented. T hese are based on the reference U NIX implemen¬ 
tation; no other documentation isavailable. 

■ A new command, mode reader, isprovided. Thiscommand causes the server to pass the connection on to nnrpd. The 
command mode query is intended for future use and is currently treated the same way. 

■ A new command, xrepiic news .group:art [ ,news .group: art ], is provided. This is simi lar to the ihave command (the 
same reply codes are used) except for the data that follows the command word. T he data consists of entries separated by 
a single comma. Each entry consists of a newsgroup name, a colon, and an article number. Once processed, the article is 
filed in the newsgroup and article numbers specified in thecommand. 

■ A new command, xpath messaged, isprovided. The server responds with a 223 response and a space-separated list of 
filenames where the article was fi led. 

■ The only other commands implemented are head, help, ihave, quit, and stat. 

HEADER MODIFICATIONS 

innd modifies as few article headers as possible, although it could be better in this area. 

T he following headers, if present, are removed: 

D ate-Received 
Posted 

Posting-Version 
Received 
Relay-Version 

E mpty headers and headers that consist of nothi ng but whitespace are also dropped. 

T he local site's name and an exclamation point are prepended to the Path header. 

TheXref header isremoved. I f thearticle iscross-posted, anew header is generated. 

The Lines header is added if it is missing. 

innd does not rewrite incorrect headers. For example it does not replace an incorrect Lines header but rqects the article 

LOGGING 

innd reports all incoming articles in its log file. This is a text file with a variable number of space-separated fields in one of the 
following formats: 

mon dd hh:mm:ss.mmm + feed <Message-ID>site... 
mon dd hh:mm:ss.mmm j feed <Message-ID> site... 
mon dd hh:mm:ss.mmm c feed <Message-ID> site... 
mon dd hh:mm:ss.mmm - feed <Message-ID> reason... 

The first three fields are the date and time to millisecond resolution. The fifth field is the site that sent the article (based on 
the Path header), and thesixth field isthe article's M essage-ID; they will contain a question mark if the information isnot 
available. 

The fourth field indicates whether the article was accepted. If it is a plussign, the article was accepted. If it isthe letter j, the 
article was accepted, but all of newsgroups have a j in their active field, so the article was filed into the "junk" newsgroup. If 
the fourth field isthe letter c, a cancel message was accepted before the original article arrived. In all three cases, thearticle 
has been accepted and the site. .. field contains the space-separated list of sites to which the article is sent. 

If the fourth field is a minus sign, the article was rejected. The reasons for rejection include 
%s header too long 
%s wants to cancel <$ss> by %s 
Article exceeds local limit of %s bytes 
Article posted in thefuture— %s 
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Bad %s header 
Can't write history 
Duplicate 
Duplicate %s header 
EOF in headers 
Linecount%s !=%s +- %s 
M issing %s header 
N o body 

N o colon-space in %s header 
N o space 

Space before colon in %s header 

Too old— %s 

Unapproved for%s 

U nwanted newsgroup %s 

Unwanted distribution %s 

W hitespace in "N ewsgroups” header— %s 

W here%s, above, is replaced by more specific information. 

N otethat if an article is accepted and none of the newsgroups are valid, it is logged with both two lines, a j line and a minus 
sign line. 

innd also makes extensive reports through sysiog. The first word of the log message is the name of the site if the entry is site- 
specific (such as a connected message). T he first word is me if the message relates to the server itself, such as when a read error 
occurs. 

If the second word is the four letters cant, an error is being reported. In this case, the next two words generally name the 
system call or library routine that failed and the object upon which the action was performed. The rest of the line might 
contain other information. 

In other cases, the second word attempts to summarize what change has been made, and the rest of the line gives more 
specific information. The word internal generally indicates an internal logic error. 

HISTORY 

W ritten by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

active(5), ctlinnd(8), dbz(3z), history(5), hosts.nntp(5), inn.conf(5), newsfeeds(5), nnrpd(8), rnews(l), syslog(8) 

innxmit 

innxmit — Send U senet articles to a remoteN NTP server. 

SYNOPSIS 

innxmit [ -A a 11 _ s poo I ][-a ][-d ][-M ][-r ][-t timeout ] 

[-T timeout ][-p ][-S ] host file 

DESCRIPTION 

innxmit connects to theN N TP server at the specified host and sends it the articles specified in the batchfile named file. It is 
usually invoked by a script run out of cron(8) that usesshiock(l) to lock the hostname followed by actiinnd(8) command to 
flush the batchfile. 
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innxmit usually blocks until the connection is made. T o specify a timeout on how long to try to make the connection, use the 
-t flag. T o specify the total amount of time that should be allowed for article transfers, use the -t flag. The default is to wait 
until an I/O error occurs or all thearticles have been transferred. I f the -t flag is used, the time ischecked just before an 
article is started; it does not abort a transfer that is in progress. Both values are measured in seconds 

If thefileisnot an absolute pathname it is taken relative to the /news/spooi/out. going directory. It is usually written by 
specifying the wnra flags in thenewsfeeds(5) file. Each line in the batchfile should be in one of the following formats: 

filename Message-1 D 
f i I e n a me 

The filename field names the article to be sent. If it is not an absolute pathname it is taken relative to the news spool 
directory, /news/spooi. If theMessage-iD field is not specified, itisobtained by scanning the article Thefiiename and 
Message-id fields are separated by a space. 

If a communication error such asawrite(2) failure occurs, innxmit stops sending and rewrites the batchfile to contain the 
current article and any other unsent articles. 

If the remote server sends an unexpected reply code, innxmit requeues the article and proceeds. U se the -r flag if the article 
should not be requeued. 

Upon exit, innxmit reports transfer and C PU usage statistics via sysiog(3). If the -v flag is used, they are also printed on the 
standard output. If all articles were sent successfully, innxmit removes the batchfile; otherwise, it rewrites it to contain the list 
of unsent articles. If no articles were sent or rejected, the file is left untouched. This can cause the batchfile to grow 
excessively large if many articles have been expired and there are communication problems. T o always rewrite the batchfile, 
use the -a flag. If the -p flag is given, then no connection is made and the batchfile is purged of entries that refer to files that 
no longer exist. This implies the -a flag. 

If the-s flag is given, then innxmit offers articles to the specified host using the xrepiic protocol extension described in 
innd(8). T o use this flag, the input file must contain the history data (com mas are transliterated to spaces by the server). For 
this flag to be used, the input must contain the necessary history entries. This is usually done by setting up awnR entry in the 
newsfeeds file. 

Use the -d flag to print debugging information on standard error. This shows the protocol transactions between innxmit and 
the N N T P server on the remote host. 

If the -m flag is used, innxmit scans an article's headers before sending it. If the article appears to be a M IM E article that is not 
in seven-bit format, the article is sent in "quoted-printable" form. 

The -a flag may be used to specify an alternate spool directory to use if the article is not found; this is usually an N FS- 
mounted spool directory of a master server with longer expiration times. 

HISTORY 

W ritten by Rich $alz (nsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

ctlinnd(8), innd(8), newsfeeds(5), shlock(l) 


iperm 

ipcrm— Remove ipc facilities. 

SYNOPSIS 

ipcrm [ shm | msg | sem ] i d 

DESCRIPTION 

ipcrm removes the resource specified by i d. 
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SEE ALSO 

ipcs(8) 

AUTHOR 

Krishna Balasubramanian (baiasub@cis.ohio-state.edu) 


Linux0.99, 9 October 1993 


ipcs 

ipcs— Provide information on ipc facilities. 

SYNOPSIS 

ipcs [ -asmq ] [ -tclup ] 
ipcs [ -smq ] -i id 
ipcs -h 

DESCRIPTION 

ipcs provides information on the ipc facilities for which the calling process has read access. 

The -i option allows a specific resource! d to be specified. Only information on thisi d is printed. 
Resources may be specified as follows: 


-m 

Shared memory segments 

•q 

M essage queues 

•s 

Semaphore arrays 

-a 

All (this is the default) 

T he output format may be specified as follows: 

-t 

Time 

-P 

PID 

•c 

C reator 

-1 

Limits 

-u 

Summary 

SEE ALSO 



ipcrm(8) 

AUTHOR 

Krishna Balasubramanian (baiasub@cis.ohio-state.edu) 

Linux 0.99, 9 October 1993 


kbdrate 

kbdrate— Reset the keyboard repeat rate and delay time. 

SYNOPSIS 

kbdrate [ -s ] [ -r rate ][-d delay ] 



klogd 



DESCRIPTION 

kbdrate is used to change the IBM keyboard repeat rate and delay time. The delay is the amount of time that a key must be 
pressed before it starts to repeat. Using kbdrate without any optionsresets the rate to 10.9 characters per second (cps) and 
the del ay to 250 mi II iseconds (ms). T hese are the IB M defaults 

OPTIONS 

-S 

-r rate 


-d del ay 

BUGS 

N ot all keyboards support all rates. 

Not all keyboards have the rates mapped in thesameway. 

Setting the repeat rate on the Gateway A nyKey keyboard does not work. If someone with a Gateway figures out howto 
program the keyboard, please send mail to taith@cs.unc.edu. 

FILES 

/etc/rc.local 
/dev/port 


Silent. No messages are printed. 

Change the keyboard repeat rate to rate cps. The allowable range isfrom 2.0 to 30.0 cps. Only certain 
specific values are possible, and the program selects the nearest possible value to the one specified. The 
possible values are given, in characters per second, as follows: 2 . 0 , 2 . 1 , 2 . 3 , 2 . 5 , 2 . 7 , 3 . 0 ,3.3,3.7, 4 . 0 , 4 . 3 , 

4.6, 5.0, 5.5, 6.0, 6.7, 7.5, 8.0, 8.6, 9.2, 10.0, 10.9, 12.0, 13.3, 15.0, 16.0, 17.1, 18.5, 20.0, 21 .8, 24.0, 

26.7, 30.0. 

Change the delay to delay milliseconds. The allowable range isfrom 250 to 1000 ms, but the only possible 
values (based on hardware restrictions) are 250 ms, 500 ms, 750 ms, and 1000 ms. 


AUTHOR 


Rik Faith (faith@cs.unc.edu) 


Linux 1.1.19, 22Junel994 


klogd 

kiogd— Kernel log daemon. 

SYNOPSIS 

klogd -c [n] -d -f [f na me] -os 

DESCRIPTION 

kiogd isa system daemon that intercepts and logs Linux kernel messages. 

OPTIONS 

-c Sets the default log level of console messages to [n ]. 

-d Enables debugging mode. This will generate a lot of output to stderr. 

-f Logs messages to the specified filename rather than to thesysiog facility. 

-0 Execute in one-shot mode. This causes kiogd to read and log all the messages that are found in the kernel 

message buffers. After a single read and log cycle, the daemon exits 
-s Force kiogd to usethesystem call interface to thekernel message buffers. 
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OVERVIEW 

The functionality of kiogd has been typically incorporated into other versions of sysiogd, but this seems to be a poor place 
for it. In the modern Linux kernel, anumberof kernel messaging issues such assourcingand prioritization must be 
addressed. Incorporating kernel logging into a separate process appears to offer a cleaner separation of services. 

In Linux, there are two potential sources of kernel log information: the/proc filesystem and thesyscaii (sys_sysiog) 
interface, although ultimately they are one and the same, kiogd is designed to choose whichever source of information is the 
most appropriate. 11 does this by first checking for the presence of a mounted /proc filesystem. If thisisfound, the 
/proc/kmsg file is used as the source of kernel log information. If the proc filesystem is not mounted, kiogd uses a system call 
to obtain kernel messages. The command-line switch (-s) can be used to force kiogd to use the system call interface as its 
messaging source. 

If kernel messages are directed through the sysiogd daemon, the kiogd daemon, as of version 1.1, has the ability to properly 
prioritize kernel messages. Prioritization of the kernel messages was added at approximately the pii3 level of the kernel. The 
raw kernel messages are of the form: 

< [ 0-7 ] >S o me t hi ng said by the kernel. 

T he priority of the kernel message is encoded as a single numeric digit enclosed inside the <> pair. The definitions of these 
values is given in the kernel include file kernei.h. W hen a message is received from the kernel, the kiogd daemon reads this 
priority level and assigns the appropriate priority level to thesysiog message. If fileoutput (-t) isused, theprioritization 
sequence is left prepended to the kernel message. 

Thekiogd daemon also allows the abi lity to alter the presentation of kernel messages to the system console. Consequent with 
theprioritization of kernel messages was the inclusion of default messaging levels for the kernel. In a stock kernel, the default 
console log level isset to 7. Any messages with apriority level numerically lower than 7 (higher priority) appear on the 
console 

M essages of priority level 7 are considered to be debug messages and do not appear on the console. M any administrators, 
particularly in a multi-user environment, prefer that all kernel messages be handled by kiogd and either directed to a file or 
to the sysiogd daemon. T his prevents nuisance messages such as line printer out of paper or disk change detected from 
cluttering the console 

By default, thekiogd daemon executes a system call to inhibit all kernel messages (except for panics) from being displayed on 
the console. The-c switch can be used to alter this behavior. The argument given to the-c switch specifies the priority level 
of messages that are directed to the console. Note that messages of a priority value lower than theindicated number are 
directed to the console. 

For example, to have the kernel display all messages with a priority level of 3 (kern err) or more severe the following 
command is executed: 

kiogd -c 4 

T he definitions of the numeric values for kernel messages are given in the file kernei.h, which can befound in the 
/usr/inciude/iinux directory if the kernel sources are installed. These values parallel thesysiog priority values, which are 
defined in thefile sysiog.h, found in the /usr/inciude/sys subdirectory. 

Thekiogd daemon can also beused in aone-shot modefor reading the kernel message buffers. One-shot mode is selected by 
specifying the -o switch on the command line. Output is directed to either the sysiogd daemon or to an alternate file 
specified by the -t switch. 

For example, to read all the kernel messages after a system boot and record them in a file called krni.msg, the following 
command is given: 
kiogd -o -f ./krni.msg 

SIGNAL HANDLING 

T he kiogd daemon responds to six signals: sighup, sigint, sigkill, sigterm, sigtstp, and sigcont. T he sigint, sigkill, 
sigterm, and sighup signals cause the daemon to close its kernel log sources and terminate gracefully. 
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ThesiGTSTP and sigcont signals are used to start and stop kernel logging. Upon receipt of asiGTSTP signal, the daemon closes 
its log sources and spins in an idle loop. Subsequent receipt of a sigcont signal causes the daemon to go through its 
initialization sequence and rechoose an input source. Using sigstop and sigcont in combination, the kernel log input can be 
rechosen without stopping and restarting the daemon. For example, if the /proc filesystem is to be unmounted, the following 
command sequence should beused: 

# kill -TSTP pid 

# umount /proc 

# kill -CONT pid 

N otationswill be made in the system logs with log info priority documenting the start/stop of logging. 

FILES 

/proc/kmsg 

BUGS 

Probably numerous. Well-formed context diffsappreciated. 

AUTHOR 

D r. Greg Wettstein (greg%wind. uucp@piains.nodak.edu), E nj el lie Systems D evelopment, Oncology Research D i vision 
Computing Facility, Roger M arisCancer Center, Fargo, ND 58122. 

Verson 1.1, 28 January 1994 
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ipc — Line printer control program. 

SYNOPSIS 

lpc [command [argument ...]] 

DESCRIPTION 

ipc is used by the system administrator to control the operation of the line printer system. For each line printer configured in 
/etc/printcap, ipe may be used to 

■ D isable or enable a printer 

■ D isable or enable a printer'sspooling queue 

■ Rearrange the order ofjobsin a spooling queue 

■ Find the status of printers and their associated spooling queues and printer daemons 

Without any arguments, ipc prompts for commands from the standard input. If arguments are supplied, ipc interprets the 
first argument as a command and the remaining arguments as parameters to the command. T he standard input may be 
redirected, causing ipc to read commands from file. Commands may be abbreviated; the following isthe list of recognized 
commands: 

? [ command ... [help [ command ... ] Print a short description of each command specified in the argument 

list or, if no arguments are given, a list of the recognized commands, 
ic abort no ail - printer Termi nate an active spooling daemon on the local host immediately 

and then disable printing (preventing new daemonsfrom being 
started by ipr) for the specified printers. 

clean no aii - printer Remove any temporary files, data fi les, and control files that cannot 

be printed (that is, they do not form a complete printer job) from the 
specified printer queues on the local machine. 

disable no all - printer Turn the specified printer queues off. This prevents new printer jobs 

from being entered into the queue by ipr. 



Part VIII: Administration and Privileged Commands 



Ic down No all - printer message ... 


enable No all - - printer 
exit, quit 

restart all - printer 


start all - printer 
status No all - printer 
stop all - printer 

topq printer [ j obnum ... ] [ user ... ] 
up all - printer 


T urn the specified printer queue off, disable printing, and put message 
in the printer status file. The message doesn't need to be quoted; the 
remaining arguments are treated like echo(l). T his is usually used to 
take a printer down and let others know why ipq(l) indicates the 
printer isdown and print the status message. 

Enable spooling on thelocal queue for the listed printers. T his allows 
ipr(l) to put new jobs in the spool queue. 

Exit from ipc. 

Attempt to start a new printer daemon. This is useful when some 
abnormal condition causes the daemon to die unexpectedly leaving 
jobs in the queue. ipq reports that there is no daemon present when 
thiscondition occurs. If the user is the super-user, try to abort the 
current daemon first (that is, kill and restart a stuck daemon). 

Enable printing and start a spooling daemon for the listed printers. 

D i splay the status of daemons and queues on thelocal machine. 

Stop a spooling daemon after the current job completes and disable 
printing. 

Place the jobs in the order listed at the top of the printer queue. 
Enable everything and startanew printer daemon. U ndoes the effects 
of down. 


FILES 

/etc/printcap 

/var/spool/* 

/var/spool/*/lock 


printer description file 
spool directories 
lock file for queue control 


SEE ALSO 

lpd(8), lpr(l), lpq(l), lprm(l), printcap(5) 

DIAGNOSTICS 

?Ambiguous command Abbreviation matches more than one command. 

?Invalid command N 0 match W3S found. 

’Privileged command C ommand can be executed by root only. 

HISTORY 

Theipc command appeared in BSD 4.2. 

BSD 4.2,16 March 1991 


lpd 

ipd — Line printer spooler daemon. 

SYNOPSIS 

lpd [-1] [port#] 

DESCRIPTION 

ipd is the line printer daemon (spool area handler) and is usually invoked at boot time from therc(8) file. It makes a single 
passthrough theprintcap(5) file to find out about the existing printers and prints any files left after a crash. It then uses the 
system calls iisten(2) and accept(2) to receive requests to print files in the queue, transfer files to the spooling area, display 
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the queue, or removejobsfrom the queue. In each case, it forks a child to handle the request so the parent can continue to 
listen for more requests. 

Avai lable opti ons: 

-l The -lflag causes ipd to log valid requests received from the network. This can be useful for 

debugging purposes. 

port# The Internet port number used to rendezvous with other processes is usually obtained with 

getservbyname(3) but can be changed with the port# argument. 


Access control is provided by two means. First, all requests must come from one of the machines listed in the file /etc/ 
hosts, equiv or /etc/hosts, ipd. Second, if the rs capability is specified in theprmtcap entry for the printer being accessed, 
ipr requests areonly honored for those users with accounts on the machine with the printer. 

Thefilemintree in each spool directory contains the number of disk blocks to leave free so that the line printer queue won't 
completely fill the disk. T he minfree file can be edited with your favorite text editor. 


The daemon begins processing files after it has successfully set the lock for exclusive access (described later) and scans the 
spool directory for files beginning with cf. Lines in each cf file specify files to be printed or non-printing actions to be 
performed. Each such linebeginswith a key character to specify what to do with the remainder of the line: 


j 

c 

L 

T 

H 

P 

M 

f 

1 

P 

t 

n 

r 

0 

c 

V 

r 

1 

2 

3 

4 
W 
I 
U 
N 


Job name. String to be used for the job name on the burst page. 

Classification. String to be used for the classification line on the burst page. 

Literal. The line contains identification info from the password file and causes the banner page 
to be printed. 

Title. Stringto beused as the title for pr(l). 

H ost name. N ameof themachinewhereipr was invoked. 

Person. Login name of the person who invoked ipr. This is used to verify ownership by iprm. 
Send mail to the specified user when the current print job completes. 

Formatted file. N ameof afileto print which is already formatted. 

Like f but passes control characters and does not make page breaks. 

Nameofafileto print using pr(l) asafilter. 

T raff file. The file contains troff(l) output (cat photo typesetter commands). 

D itroff file. The file contains device independent troff output. 

DVI file. The file contains Tex I output D VI format from Standford. 

Graph file. The file contains data produced by piot(3). 

Cifplotfile Thefile contains data produced by citpiot. 

Thefilecontainsa raster image. 

Thefile containstext data with FORTRAN carriage control characters. 

T raff font R. N ameof the font file to use instead of the default. 

T raff font I. N ameof thefont file to use instead of the default. 

T raff font B. Name of thefont file to use instead of the default. 

T raff fonts. N ameof the font file to use instead of the default. 

Width. Changes the page width (in characters) used by pr(l) and the text filters. 

Indent. The number of characters to indent the output by (in ASCII). 

Unlink. N ameof file to remove upon completion of printing. 

Filename. The name of the file that is being printed or a blank for the standard input (when ipr 
isinvoked in a pipeline). 


If a file cannot be opened, a message is logged via sysiog(3) using the log lpr facility, ipd tries up to 20 times to reopen afile 
it expects to be there, afterwhich it skips the fi le to be printed. 
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ipd usestiock(2) to provide exclusive access to the lock file and to prevent multiple daemons from becoming active 
simultaneously. If the daemon should be killed or die unexpectedly, the lock file need not be removed. The lock file is kept 
in a readable ASCII form and contains two lines. The first is the process ID of the daemon and the second is the control 
filename of the current job being printed. The second line is updated to reflect the current status of ipd for the programs 
lpq(l) and lprm(l). 

FILES 

/etc/printcap 
/var/spool/* 

/var/spool/*/mintree 
/dev/lp* 

/dev/printer 
/etc/hosts.equiv 
/etc/hosts.Ipd 

SEE ALSO 

lpc(8), pac(l), lpr(l), lpq(l), lprm(l), syslog(3), printcap(5) 

4.2 BSD Line Printer Spooler M anual 

HISTORY 

An ipd daemon appeared in Version 6, AT&T U N IX. 

BSD 4.2,16 March 1991 


Printer description file 

Spool directories 

M inimum free space to leave 

Line printer devices 

Socket for local requests 

Listsmachinenamesallowed printer access 

Lists machine names allowed printer access but not under same administrative control 


MAKEDEV 

makedev— C reates and maintains filesystem device entries. 

SYNOPSIS 

MAKEDEV [ -vcdnhV ] device or device-group names 

DESCRIPTION 

makedev is used to maintain the special filesystem entries found in /dev. It creates, or optionally removes, one or more device 
entries. The names and device numbers are defined in the devinfo file (q.v.); site-specific configuration is found in the file 
makedev. ctg. makedev itself has no knowledge of device information. 


OPTIONS 

-V 

Verbose mode; print out exactly what's being done. 

-C 

Create; create the specified devices (default). 

-d 

Delete; remove the specified devices instead of creating them. 

-n 

Do nothing; only print what would be done Implies -v as well 

-h 

Print a usage message. 

-V 

Print the version string. 


The fo Mowing targets are spec i al: 

update Run makedev in update mode. This reads the list of devices currently available from 

/proc/devices and updates all entries in /dev to match the device numbers found there. 
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local Run makedev to create local devices. This option is obsolete and just prints a warning message. 

Usedevinto. local and makedev.cfg to achieve the same results 


FILES 

/etc/devinfo 

/usr/local/etc/devinfo. local 
/etc/devinfo.local 
/etc/makedev.cfg 
MAKEDEV. cache 
/proc/devices 


Device information 

Local device information 

Alternate location for local device information 

Configuration file 

Cached data for update 

T he kernel's list of current da/ices 


AUTHOR 

David A. H olland (dhoiiand?husc. hanvard.edu). Based on the older makedev shell script written by N ick Holloway. Addi¬ 
tional ideas were contributed by Rik Faith. 

NOTES 

T he lalr(1) parser generator used to build makedev. c from makedev.syn is a commercial product. You won't be able to do a 
complete rebuild uni ess you have it. 

SEE ALSO 

devinfo(5), makedev.cfg(5) 

Version 1.5, March 1995 


MAKEDEV 

makedev— C reates devices. 

SYNOPSIS 

cd dev; ./MAKEDEV -V 

cd dev; ./MAKEDEV [ -n ] [ -v ] update 

cd dev; ./MAKEDEV [ -n ] [ -v ] [ -d ] device ... 

DESCRIPTION 

makedev is a script that creates the devices in /dev used to interface with drivers in the kernel. 

NotethatprogramsgivingtheerrorENOENT: no such file or directory usually means that the devi ce file is missi ng, whereas 
enodev: No such device usually means the kernel does not have the driver configured or loaded. 

OPTIONS 

-v Print out version (actually RCS version information) and exit. 

-r D o n ot actual Iy u pdate the d evi ces j ust pri nt th e acti ons th at wou I d be perfo rm ed. 

-d Delete the devices. The main use for this flag is by makedev itself. 

-v Beverbose. Print out the actions as they are performed. This is the same output as produced by -r. 


CUSTOMIZATION 

Because there is currently no standardization in what names are used for system users and groups, it is possible that you 
might need to modify makedev to reflect your site's settings. N ear the top of the file is a mapping from device type to user, 
group, and permissions (For example, all CD-ROM devices are set from thescdrom variable.) If you want to change the 
defaults this is the section to edit. 
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DEVICES 

General Options 


update 

generic 

%std 

local 

Virtual T erminals 

This only works on kernels that have/proc/interrupts (introduced during 1.1.x). This file is 
scanned to see what devices are currently configured into the kernel, and this is compared with 
the previous settings stored in the file called devices. Devices that are new si nee then or have a 
different major number are created, and those that are no longer configured are deleted. 

Create a generic subset of devices. This is the standard devices, plus floppy drives, various hard 
drives, pseudo-terminals, console devices, basic serial devices, busmice, and printer ports 
Standard devices. These are mem, access to physical memory; kmem, access to kernel virtual 
memory; nun, null device(infinitesink); port, accessto I/O ports zero, null byte source 
(infinite source); core, symiink to /proc/kcore (for kernel debugging); fun, always returns 
enospace on write; ram, ramdisk; tty, to access the controlling tty of a process. 

This simply runs makedev. local. This is a script that can create any local devices. 

console 

Thiscreatesthedevices associated with theconsole. T his is the virtual terminals tty*, where* 
can be from 0 though 63. The device tty0 is the currently active vt and is also known as console. 
For each vt, there are two devices, ves* and vesax, which are used to generate screen-dumps of 
thevt (thevesx is just thetext and vesax includes the attributes). 

Serial D e/ices 

ttyS{0..63} 

Serial ports and corresponding dial-out device. For device ttysx, there is also thedevicecuax, 
which is used to dial out with. This can avoid the need for cooperative locks in simple 
situations. 

cyclades 

D ial-in and dial-out devices for the cyclades intelligent I/O serial card. The dial in device is 
ttyc* and the corresponding dial-out device iscub*. By default, devices for 7 lines are created, 
but this can be changed to 15 by removing the comment. 

Pseudo Terminals 

pty[p- s ] 

Each possible argument will create a bank of 16 master and slave pairs. The current kernel (1.2) 
is limited to 64 such pairs The master pseudo-terminals are pty [p-s no -9a -ti and the slaves are 

tty [ p-s ][0-9a-f]. 

Parallel Ports 

IP 

Standard parallel ports. The devices are created ip@, ipi, and ip 2 . These correspond to ports at 
0x3bc, 0x378, and 0x278. FI ence, on some machines, the first printer port may actually beipi. 

par 

Alternative to ip. Ports are named parx instead of ipx. 

BusM ice 

busmice 

The various bus mice devices. This creates the foil owing devices: logimouse (Logitech bus 
mouse), psmouse (PS/2-style mouse), msmouse (M icrosoft Inport bus mouse), atimouse (ATI XL 
bus mouse) and jmouse (J-mouse). 

Joystick Devices 

is 

Joystick. Creates j so and j si. 

D isk D e/ices 

fd[0-7] 

Floppy disk devices. The devicefdx isthedevicethatautodetectstheformat, and theadditional 
devices are fixed format (whose size is indicated in the name). The other devices are named as 
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hd [ a - d ] 


xd[a-d] 
sd [ a - h ] 

loop 


fdxLn. The single letter L identifies the type of floppy disk (d =5.25" D D, h =5.25" H D, 
d =3.5" D D, h =3.5" H D, e =3.5" ED). The number n represents the capacity of that format 
in KB. Thus the standard formats are tdx d360, fdx hi 200 , fdxD720, tdxHi440, and tdxE 2880 . 

For more information, see Alain K naff's fdutiis pack-age. 

Devicestd0* through td3* are floppy disks on the first controller, and devices td4* through fd7* 
are floppy disks on the second controller. 

AT hard disks. The device hdx provides access to the whole disk, with the partitions being 
hdx [ 0 - 20 ], The four primary partitions are hdx 1 through hdx 4 , with the logical partitions being 
numbered from hdx 5 though hdx 20 . (A primary partition can be made into an extended 
partition, which can hold four logical partitions). By default, only the devices for four logical 
partitions are made. T he others can be made by uncommenting them. 

D rives hda and hdb are the two on the first controller. If using the new IDE driver (rather than 
theold H D driver), then hdc and hdd arethetwo drives on thesecondary controller. These 
devicescan also be used to accessIDE CD-ROMs if using the new IDE driver. 

XT harddisks. Partitions are the same as ID E disks. 

SCSI hard disks. The partitions are similar to the ID E disks, but there is a limit of 11 logical 
partitions (sdx 5 through sdx 15 ). Thisisto allow 8 SCSI disks. 

Loopback disk devices. These allow you to use a regular file as a block device. This means that 
images of filesystems can be mounted and used as normal. This creates 8 devices ioop 0 through 

100p7. 


Tape Devices 


St[0-7] 

qic 

ftape 

CD-ROM Devices 

SC SI tapes. This creates the rewinding tape device stx and the non-rewi nding tape device nstx. 
QIC-80 tapes. The devices created arermt8, rmtie, tape-d, and tape-reset. 

F loppy driver tapes (Q1C -117). T here are four methods of access dependi ng on the floppy tape 
drive. For each of the access methods 0,1, 2, and 3, thedevicesrftx (rewinding) and nrftx 
(non-rewinding) are created. For compatibility, devices ftape and nftape aresymlinksto rtto 
and nrft 0 . 

scd[0-7] 

SCSI CD players. 

sonycd 

Sony CDU-31A CD player. 

mcd 

M itsumi CD player. 

cdu535 

Sony CDU-535 CD player. 

lmscd 

LM S/PhilipsC D player. 

sbpcd{,1,2,3} 

SoundBlaster CD player. The kernel is capable of supporting 16 CD-ROM s, each of which is 
accessed as sbpcd[0-9a-f ]. These are assigned in groups of four to each controller, sbpcd isa 
symlink to sbpcd 0 . 

Scanner 

logiscan 

Logitech ScanM an32 and ScanM an 256. 

m105scan 

M ustek M 105 H andscanner. 

ac4096 

Audio 

A4T ek C olor H andscanner. 


audio This creates the audio devices used by the sound driver. These include mixer, sequencer, dsp, 

and audio. 

Devices for the PC Speaker sound driver. These are pcmixer, pxsp, and pcaudio. 


pcaudio 
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M ixdlaneous 


sg 


fd 


ibcs2 

apm 

dcf 


Generic SCSI devices. The devices created aresgo through sg7. These allow arbitrary commands 
to be sent to any SCSI device. This allows for querying information about the device or 
controlling SCSI devices that are not one of disk, tape, or CD-ROM (for example, a scanner or 
writable CD-ROM). 

T o allow an arbitrary program to be fed input from file descriptor*, use /dev/td/x as the 
filename. This also creates BR/dev/stdm, BR/dev/stdout, and BR/dev/stdem. (N ote that these are 
justsymlinksinto /proc/seif/fd.) 

Devices (and symlinks) needed by the IBCS2 emulation. 

D evicesfor power management. 

Driver for DCF-77 radio clock. 


helloworld 


Kernel modules demonstration device. See the modules source. 


N etwork devices Linux used to have devices in / dev for controlling network devices, but that is no longer the 

case. T o see what network devices are known by the kernel, look at /proc/net/dev. 


SEE ALSO 

Linux Allocated Devices, maintained by H. Peter Anvin (peter.Anvin@imux.org) 

AUTHOR 

N ick Holloway 

Linux, 14 August 1994 


mke2fs 

mke 2 ts— C reate a Linux second extended filesystem. 

SYNOPSIS 

mke2fs [ -c | -1 filename ] [ -b block-size ] [ -f fragment-size ] 

[ -i bytes-per-i node ] [ -m reserved-bl ocks-per cent age ] [ -q ][-v ][-S ] 
devi ce [ blocks-count ] 


DESCRIPTION 

mke 2 ts is used to create a Linux second extended filesystem on a device (usually a disk partition), devi ce is the special file 
corresponding to the device (such as/dev/hdxx). bl ocks-count is the number of blocks on the device. If omitted, mke 2 fs 
automatically figures the filesystem size. 


OPTIONS 

-b bl ock- si ze 
-c 


-f fragment-si ze 
-i byt es - per■i no de 


-1 f i I e n a me 

-m reserved- bl ocks-percentage 


Specify thesize of blocks in bytes. 

Check the device for bad blocks before creating the filesystem using a fast read-only 
test. 

Specify the size of fragments in bytes. 

Specify the byte^i node ratio. mke 2 fs creates an inode for every bytes - per- i node bytes 
of space on the disk. This value defaults to 4096 bytes, bytes - per - i node must beat 
least 1024 . 

Read the bad blocks list from f i i e n a me. 

Specify the percentage of reserved blocks for the super-user. T his value defaults to 5 
percent. 

Quiet execution. U seful if mke 2 fs is run in a script. 

Verbose execution. 



-s 


Write superblock and group descriptors only. This is useful if all the superblock and 
backup superblocks are corrupted and a last-ditch recovery method is desi red. It 
causes mke 2 fs to reinitialize the superblock and group descriptors while not touching 
the inode table and the block and inode bitmaps. The e 2 fsck program should be run 
immediately after thisoption is used, and there isno guarantee that any data will be 
salvageable. 


AUTHOR 

T his version of mke 2 fs has been written by Theodore T'so (tytso@mit.edu). 

BUGS 

mke 2 ts accepts the -f option but currently ignores it becausethe second extended filesystem does not support fragments yet. 
There may be some other bugs. Please report them to the author. 

AVAILABILITY 

mke 2 f s is available for anonymous FT P from ftp.ibp.fr and tsx- 11 .mit. edu in /pub/linux/packages/ext 2 f s. 

SEE ALSO 

badblocks(8), dumpe2fs(8), e2fsck(8), tune2fs(8) 

Version 0.5b, N ovemberl994 


mkfs 

mkfs — Build a Linux filesystem. 

SYNOPSIS 

mkfs [ -V ][-t fstype ] [f s-opt i o ns ] filesys [ blocks ] 


DESCRIPTION 

mkfs is used to build a Linux filesystem on a device, usually a hard disk partition, fi i esys is either the device name (such as/ 
dev/hdai, /dev/sdb 2 > or the mount point (such as/, /usr, /home) for the filesystem, blocks is the number of blocks to be used 
for the filesystem. 

The exit code returned by mkfs iso on success and i on failure. 

In actuality, mkfs is simply a front end for the various filesystem builders (mkfs. fstype) avai lable under Linux. T he fi lesystem- 
specific builder issearched for in /etc/fs first, then in /etc, and finally in the directories listed in thePATH environment 
variable. Please see the fi lesystem-specific builder manual pages for further details. 


OPTIONS 

-v 


-tfstype 


fs-options 

•c 

- If i I e n a me 
-v 


Produce verbose output, including all fi lesystem-specific commands that are executed. 
Specifying thisoption more than once inhibits execution of any filesystem-specific commands. 
This is really only useful fortesting. 

Specifies the type of filesystem to be built. If not specified, the type is deduced by searching for 
filesys in /etc/fstab and using the corresponding entry. If the type cannot be deduced, the 
default filesystem type (currently minix) is used. 

Filesystem-specific options to be passed to the real filesystem builder. Although not guaranteed, 
thefollowing options are supported by most filesystem builders. 

C heck the device for bad blocks before bui Iding the filesystem. 

Read the bad blocks list from f i i ename. 

Produce verbose output. 
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BUGS 

All generic options must precede and not be combined with filesystem-specific options. Some filesystem-specific programs do 
not support the -v (verbose) option nor return meaningful exit codes. Also, somefilesystem-specific programs do not 
automatically detect the device size and require the blocks parameter to be specified. 

AUTHORS 

D avid Engel (davidUods.com), Fred N . van Kempen (waltje@uwalt. nl.mugnet.org), and Ron Sommeling (sommel@sci.kun.nl). 
The manual page was shamelessly adapted from Remy Card's version fortheext 2 filesystem. 

SEE ALSO 

fsck(8), mkfs.minix(8), mkfs.ext(8), mkfs.ext2(8), mkfs.xiafs(8) 

Version 1.9, June 1995 



mkfs 

mkts — M akea Linux M IN IX filesystem. 

SYNOPSIS 

mkfs [ -c ] [ -nnamel ength ] [ -i i nodecount ] device si ze- i n-bl ocks 
mkfs [ -1 filename ] device size-in-blocks 

DESCRIPTION 

mkfs creates a Linux M IN IX filesystem on a device (usually a disk partition). 

T he device is usually of the following form: 

/dev/hda[1-8] 

/dev/hdb[1-8] 

/dev/sda[1-8] 

/dev/sdb[ 1 -8] 

T he s i ze- i n- bi ocks parameter isthe desi red size of thefilesystem in blocks This information can be determined from the 
fdisk(8) program. 0 nly block counts strictly greater than 10 and strictly less than 65,536 are allowed. 

OPTIONS 

-c Check the device for bad blocks before creating thefilesystem. If any are found, thecountis 

printed. 

-nnamel ength Specify the maximum length of filenames. N o space is all owed between the -n and the 

name i ength. Currently, the only allowable values areu and 30.30 is the default. 

-i i no decount Specify the number of inodes for thefilesystem. 

-1 f i 1 ename Read the bad blocks list from f i 1 e na me. T he file has one bad block number per line. The count 

of bad blocks read isprinted. 

EXIT CODES 

The exit code returned bymkfs.minix is one of the following: 

0 No errors 

8 Operational error 

is U sage or syntax error 


SEE ALSO 

fsck(8), mkefs(8), efsck(8), reboot(8) 



mklost+found 


1327 


AUTHOR 

LinusTorvalds (torvaids@cs.heisinki.fi). Error codevalues by Rik Faith (faith@cs.unc.edu). Inode request feature by Scott 
H eavner (sdh@po.cwru.edu). Support for the filesystem valid flag by D r. W ettstein (greg%wind.uucp@piains.nodak.edu). 

Check to pra/ent mkfs of mounted filesystem and boot sector clearing by Daniel Quinlan (quinian@yggdrasii.com). 

Linux 0.99,10 January 1994 


mklost+found 

mkiost+found— C reate a lost+found directory on a mounted Linux second extended filesystem. 

SYNOPSIS 

mklost+found 

DESCRIPTION 

mkiost+found is used to create a lost+found directory in the current working directory on a Linux second extended filesystem, 
mkiost+found pre-allocates disk blocks to the directory to make it usable by e 2 fsck. 

OPTIONS 

There are none. 

AUTHOR 

mkiost+found was written by Remy Card (card@masi.ibp.fr), thedeveloper and maintainer of theext 2 fs. 

BUGS 

There are none.:-) 

AVAILABILITY 

mklost+found is availablefor anonymous FT P from ftp.ibp.fr and tsx -11 .mit.edu in /pub/linux/packages/ext 2 fs. 

SEE ALSO 

e2fsck(8), mke2fs(8) 

Version 0.5b , N ovember 1994 


mkswap 

mkswap — Set up a Linux swap area. 

SYNOPSIS 

mkswap [ -c ] device [size-in-blocks] 

DESCRIPTION 

mkswap setsup a Linux swap area on a device or in a file. 
T he device is usually of the following form: 

/dev/hda[1-8] 

/dev/hdb[1-8] 

/dev/sda[1-8] 

/dev/sdb[1-8] 
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T he s i z e- i it- bi oc k s parameter isthe desi red size of thefilesystem in blocks This information isdetermined automatically by 
mkswap if it is omitted. Block counts are rounded down so that the total size is an integer multiple of the machine's page size. 
Only block counts in the range mincount. .maxcount are allowed. If the block count exceeds the maxcount, it is truncated to 
that value and a warning message is issued. 

T h e m i ncount an d maxcount val ues fo r a swap area are 
MINCOUNT =10 * PAGE_SIZE / 1024 
MAXCOUNT =(page_size-10) !|! 8 *page_size /1024 

For example, on amachinewith 4KB pagesfsuch asx86), we get 
mincount = 10 * 4096 / 1024 =40 
MAXCOUNT = (4096 - 10) * 8 * 4096 / 1024 = 130752 

As each block is 1KB, the swap area in this example could have a size that is anywhere in the range from 40KB to 
127.6875MB. 

If you don't know the page size that your machine uses, you may be able to look it up with cat /proc/cpuinto. 

The reason for the limit on maxcount isthat a single page is used to hold the swap bitmap at the start of the swap area, where 
each bit represents a single page. The reason for the-10, isthat the signature isswAP-sPACE - 10 characters. 

To set up a swap file it is necessary to create that file before running mkswap. A sequence of commands similar to the 
following is reasonable for this purpose: 

# dd if=/dev/zero of=swapfile bs=1024 count=8192 

# mkswap swapfile 8192 

# sync 

# swapon swapfile 

N ote that a swap file must not contain any holes (so using cp(l) to createthefileisnot acceptable). 

OPTIONS 

-c Check the device for bad blocks before creating thefilesystem. If any are found, thecount 

is printed. This option is meant to be used for swap partitions only and should not be 
used for regular files! To make sure that regular files do not contain bad blocks, the 
partition that contains the regular fileshould have been created with mkfs -c. 

SEE ALSO 

fsck(8), mkfs(8), fdisk(8) 

AUTHOR 

LinusT orvalds (torvalds@cs.helsinki.fi) 

Linux 1.0, 8 February 1995 


mount,umount 

mount, umount— M ount and dismount fi lesystems. 

SYNOPSIS 

mount [-afrwuvn] [-t vfstype] 

mount [-frwuvn] [-o remount [,...]] special | node 

mount [-frwun] [-t vfstype] [-o options] special | node 

umount [-an] [-t vfstype] 

umount sped al j node 



mount, unmount 



DESCRIPTION 


The mount command calls the mount(2) system call to prepare and graft a special device onto the filesystem tree at the point 
node. If either sped ai or node are not provided, the appropriate information is taken from the t stab(5) file. The special 
keyword none can be used instead of a path or node specification. This is useful when mounting the proc filesystem. 

The system maintains a list of currently mounted filesystems. If no arguments are given to mount, this list is printed. 


0 ptions available for the mount command: 


async 

auto 

defaults 

dev 

exec 

noauto 

nodev 


noexec 

nosuid 

nouser 

remount 

ro 

rw 

suid 

sync 

user 


Causes everything to be done except for the actual system call; if it's not obvious, this 
"fakes" mounting the filesystem. This option is useful in conjunction with the -v flag to 
determine what the mount command is trying to do. 

Options are specified with a -o flag followed by a comma-separated string of options. 

N otethat many of these options are only useful when they appear in the /etc/f stab file. 
The following options apply to any filesystem that is being mounted: 

All I/O to the filesystem should be done asynchronously. 

C an be mounted with the -a option. 

U Se default options: rw, suid, dev, exec, auto, nouser, and async. 

Interpret character or block special devices on the filesystem. 

Permit execution of binaries. 

Can only be mounted explicitly (that is, the -a option does not cause the filesystem to 
be mounted). 

Do not interpret character or block special devices on the filesystem. This option is 
useful for a server that has filesystems containing special devices for architectures other 
than its own. 

Do not allow execution of any binaries on the mounted filesystem. This option is useful 
for a server that has fi Iesystem s contai n i ng bi nari es for arch itectu res other than its own. 
Do not allow set-user-identifier or set-group-identifier bitsto take effect. 

Forbid an ordinary (that is, non-root) user to mountthefilesystem. 

Attempt to remount an already-mounted filesystem. This is commonly used to change 
the mount flags for a filesystem, especially to make a read-only filesystem writable. 

M ountthefilesystem read-only. 

M ountthefilesystem read-write. 

Allow set-user-identifier or set-group-identifier bitsto take effect. 

All I/O to thefilesystem should be done synchronously. 

Allow an ordinary user to mountthefilesystem. Ordinary users always have the 
following options activated: noexec, nosuid, and nodev (unless overridden bythesuper- 
user by using, for example, the following option line user, exec,dev,suid. 


T hefollowing options apply only to certain filesystems: 


case=val ue 
check=vaI ue 

none 

normal 

strict 

check=vaI ue 


Forthehpfs filesystem, specify case as lower or asis. 

T ells theext 2 filesystem kernel code to do some more checks while the filesystem is 
mounted. Currently (0.99.15), the following values can be specified with thisoption: 

N o extra check is performed by the kernel code. 

Theinodesand blocks bitmaps are checked when thefilesystem ismounted (thisisthe 
default). 

In addition to the normal checks, block deallocation checks that the block to free is in 
the data zone 

Forthemsdos filesystem, three different levels of specificity can be chosen: 
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relaxed 


normal 

strict 


conv=val 


ue 


binary 

text 

auto 


Uppercase and lowercase are accepted and equivalent, long name parts are truncated (for 
example, veriongname.foobar becomes veryiong.too), leading and embedded spaces are 
accepted in each name part (name and extension). 

Like relaxed but many special characters (*, ?, <, spaces, and so on) are r^ected. This is 
the default. 

Like normal, but names may not contain long parts and special characters that are 
sometimes used on Linux but are not accepted by MS-DOS are rejected (+, =, spaces, 
and so on). 

Forthemsdos, hpfs, and iso9660 filesystems, specify file conversion as binary, text, or 
auto. Theiso9660 filesystem also allows value to bemtext. 

Themsdos filesystem can perform crlf<->nl (M S-D OS text format to UN IX text 
format) conversion in the kernel. The following conversion modes are available: 

N o translation is performed. Thisisthedefault. 
crlf<->nl translation is performed on all files. 

crlf<->nl translation is performed on all files that don't have a well-known binary 
extension. The list of known extensions can be found at the beginning of 
fs/msdos/misc .c (as Of 09913r, the list is exe, com, bin, app, sys, drv, ovl, ovr, obj, lib, 
dll, pif, arc, zip, lha, lzh, zoo, tar, z, arj, tz, taz, tzp, tpz, gif, bmp, tif, gl, jpg, pcx, 
tfm, vf, gf, pk, pxl, and dvi). 


Programs that do computed lseeks won't like in-kernel text conversion. 


For filesystems mounted in binary mode, a conversion tool (fromdos/todos) is available. 


block=vaI ue 

bsdgroups 

cruft 


debug 


debug 

errors=val ue 
continue 

remount, ro 
panic 
fat=va I ue 

gid=va I ue 
B grpid 

map=va I ue 


nocheck 

nogrpid 


For the iso9660 fi lesystem, set the block size. 

See grpid. 

Fortheiso9660 filesystem, set the cruft flag to y. This option is available because there 
are buggy premastering programs out there that leave junk in the top byte of the file 
size. This option clears the top byte but restricts files to 16M B maximum in the process. 
Forthemsdos filesystem, turn on thedebug flag. A version string and a list of filesystem 
parametersis printed. (These data are also printed if the parameters appear to be 
inconsistent.) 

Fortheext 2 fs filesystem, cause the kernel code to display thefi lesystem parameters 
when thefilesystem ismounted. 

Fortheext 2 fs filesystem, specify the error behavior: 

N o special action istaken on errors(except marking thefilesystem as erroneous). This is 
the default. 

Thefilesystem isremounted read only, and subsequent writes are refused. 

When an error is detected, the system panics. 

For themsdos filesystem, specify either a 12-bit fat or a 16-bit fat. This overrides the 
automatic FAT type detection routine. Use with caution! 

Forthemsdos and hpts filesystems, give every file a gid equal tovai ue. 

Causes the ext2fs to usetheBSD behavior when creating files: Files are created with the 
group ID of their parent directory. 

Fortheiso9660 filesystem, specify mapping as off or normal. In general, non-Rock 
Ridge discs have all thefilenamesin uppercase, and all the filenames have a ;i 
appended. The map option strips the ;i and makes the name lowercase. (See also 

norock.) 

Fortheext 2 fs, turns off checking (seecheck=none). 

C auses the ext2fs to use the System V behavior when creating files. Files are created 
with thegroup ID of the creating process, unless the setgid bit is set on the parent 
directory. This isthe default for all Linux filesystems. 



mount, unmount 



norock 


quiet 
sb=val ue 


sysvgroups 
uid=va I ue 
umask=vaI ue 


N ormal iso9600 filenames appear in a 8.3 format (that is, D 0 S-like restrictionson 
filename length), and in addition, all characters are in uppercase. Also there isno field 
for file ownership, protection, number of links, provision for block/character devices, 
and so on. 

Rock Ridge is an extension to iso9660 that provides all of these U NIX-Iike features. 
Basically, there are extensions to each directory record that supply all of the additional 
information, and when Rock Ridgeisin use, thefilesystem is indistinguishable from a 
normal U N IX filesystem (except that it is read only, of course). 

The norock switch disables the use of Rock Ridge extensions, even if available. (See also 

map.) 

Forthemsdos filesystem, turn on the quiet flag. Attempts to chown or chmod files do not 
yield errors although they fail. Use with caution! 

Fortheext 2 filesystem, use an alternate superblock located at block vai ue. value is 
numbered in 1024-byte blocks. An ext 2 filesystem usually has backups of the superblock 
at blocks 1, 8193,16385, and so on. 

See nogrpid. 

Forthemsdos and hpts filesystems, give every file a uid equal to v a i ue. 

Forthemsdos and hpts filesystems, give every file a umask of vai ue. The radix defaults to 
octal. 


Thefull set of options applied isdetermined by first extracting the options for the filesystem from thetstab table, then 
applying any options specified by the -o argument, and finally applying the -r or -w option. 


If themsdos filesystem detects an inconsistency, it reports an error and sets the filesystem to read only. Thefilesystem can be 
made writable again by remounting it. 


-r Thefilesystem object isto be mounted read only. 

-t vfstype Theargumentfollowingthe -t isused to indicate the filesystem type. Thefilesystem 

types that are currently supported are listed in iinux/fs/fiiesystems.c: minux, ext, ext 2 , 
xiaf s, msdos, hpf s, proc, nfs, iso9660, sysv, Xenix, coherent. N Ote that that last three are 
equivalent and that xenix and coherent will be removed at some point in the future; use 
sysv instead. 

The type minix is the default. If no -t option is given, or if the auto type is specified, the 
superbiock is probed for the filesystem type (minix, ext, ext 2 , and xia are supported). If 
thisprobefailsand /proc/tiiesystems exists, then all the filesystems listed are tried, 
except for those labeled nodev (such as proc and nfs). 

N ote that the auto type may be useful for user-mounted floppies. For example, the mount 
command mounts all filesystems except those of type msdos and ext: 
mount -a -t nomsdos,ext 

-v Verbose mode. 


-w Thefilesystem object isto be read and write, 

-n M ount without writing in /etc/mtab. 


umount removes the speci ai device grafted at point node from thefilesystem tree. 

Options for the umount command: 

-a All of the filesystems described in /etc/mtab are unmounted. 

Isused to indicate the actions should only betaken on filesystems of the specified type. 
M ore than one type may be specified in a comma-separated list. The list of filesystem 
types can be prefixed with no to specify thefilesystem types on which no action should 
betaken. (See example for the mount command.) 


-t vf st ype 
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FILES 

/etc/fstab 
/etc/mtab" 

/etc/mtab.tmp 

SEE ALSO 

mount(2), umount(2), fstab(5), swapon(8) 

BUGS 

It is possible for a corrupted filesystem to cause a crash. 

Some Linux filesystems don't support -o synchronous (the ext 2 fs does support synchronous updates (a la BSD) when 
mounted with the sync option). 

The -o remount may not be able to change mount parameters (all ext 2 fs parameters, except sb, are changeable with a 
remount, for example but you can't changegid or umask for thedosfs). 

HISTORY 

A mount command appeared in Version 6, AT&T UNIX. 

AUTHORS AND CONTRIBUTORS 

The Linux mount command has a long and continuing hi story. The following major releases are noted with the name of the 
primary modifier: 

0.97.3: D Oug 0 uale (quale@saavik. cs .wise. edu) 

0.98.5: H .J. Lu (hlu@eecs.wsu.edu) 

0.99.2: Rick Sladkey (jns@worid.std.com) 

0.99.6: Rick Sladkey (jrs@worid.std.com) 

0.99.10: Stephen Tweedie(sct@dcs.ed.ac.uk) 

0.99.14: Rick Sladkey (jrs@wonid.std.com) 

(Filesystem-specific information added to man page on 27 N ovember 1993 by Rik Faith with a lot of information and text 
from the following filesystem authors: Werner Almesberger, Eric You ngdale, and RemyCard.) 

Linux 1.1, 8 February 1995 

mountd 

mountd — NFS mount daemon. 

SYNOPSIS 

/usr/etc/rpc.mountd [\-f\- - exports-file\][\-dhnprv\] 

[ \ - - debug!][\--exports-file=file\] [ \ - - help!] 

[\--allow-non-root!][!--re-export!][!--version!] 

DESCRIPTION 

The mountd program is an N FS mount daemon. 

OPTIONS 

-t or - -exports-file This option specifies the exports file, listing the clients that this server is prepared to 

serve and parameters to apply to each such mount (seeexports(5)). By default, exports 
are read from /etc/exports. 


Filesystem table 
Lock file 
T emporary file 




named-xfer 



-d Of - -debug 

-h or - -help 

-n or --allow-non-root 

-p or --promiscuous 
-r or - -re-export 


-v or - -version 

SEE ALSO 

exports(5), nfsd(8), ugidd(8C) 

BUGS 

The current implementation (still) does not keep track of remote mounts. 

13 October 1993 


Log each transaction verbosely to thesysiog. 

Provide a short help summary. 

Allow incoming mount requests to be honored even if the/do not originate from 
reserved IP ports. Some older N FS client implementations require this. Some newer 
N FS client implementations don't believe in reserved port checking. 

Put the server into promiscuous mode where it will serve any host on the network. 
Allow imported N FS filesystems to be exported. This can be used to turn a machine 
into an N FS multiplier. Caution should be used when reexporting loopback N FS 
mounts because reentering the mount point results in deadlock between the N FS client 
and the NFS server. 

Report the current version number of the program. 


named-xfer 

named-xfer— Ancillary agent for inbound zone transfers. 

SYNOPSIS 

named-xfer -z zonetotransfer -f d b_ fiI e -s s e ria I no [ -d debuglevel ] 
[-1 debugl ogfi I e ][-t trace_file ] [ - p port# ][-S ] nameserver 


DESCRIPTION 


named-xfer is an ancillary program executed by named(8) to perform an inbound zonetransfer. It is rarely executed directly 
and only by system administrators who are trying to debug a zone transfer problem. See RFC s 1033,1034, and 1035 for 
more information on the Internet name-domain system. 


Options are 


-z 

-f 


-s 


-d 

-1 

-t 

-P 

-S 


Specifi es the name of the zone to be transferred. 

Specifies the name of the file into which the zone should be dumped when it is received 
from the primary server. 

Specifies the serial number of the current copy of thiszone. If the SO A RR you get from 
the primary server does not have a serial number higher than this the transfer is aborted. 
Print debugging information. A number after thed determines the level of messages 
printed. 

Specifies a log file for debugging messages. The default is system-dependent but is 
usually in /var/tmp or /usr/tmp. N ote that this only appliesif -d is also specified. 
Specifies a trace file that contains a protocol trace of the zone transfer. This is probably 
only of interest to people debugging the nameserver itself. 

U se a different port number. T he default is the standard port number as returned by 
getservbyname(3) for Service "domain". 

Perform a restricted transfer of only the SO A, N S records, and glue A records for the 
zone. The SO A record is not loaded by named but is used to determine when to verify 
theN S records. See the stubs directive in named(8) for more information. 
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Additional arguments are taken asnameserver addressesin so-called "dotted-quad" syntax only; no hostnames are allowed 
here. At least one address must be specified. Any additional addresses are tried in order if the first one fails to transfer 
successfully. 

SEE ALSO 

named(8), nesolven(3), resolver(5), hostname(7), RFC 882, RFC 883, RFC 973, RFC 974, RFC 1033, RFC 1034, RFC 
1035, RFC 1123, NameServer 0perationsGuide for BIND 

26Junel993 


named 

named— Internet domain nameserver. 

SYNOPSIS 

named [ -d debuglevel ][-p port # [ /I ocal port#]][{-b} bootfile ][-q ][-r ] 


DESCRIPTION 


named is the Internet domain nameserver. See RFC s 1033,1034, and 1035 for more information on the Internet name- 
domain system. Without any arguments, named reads the default boot file /etc/named, boot, reads any initial data, and listens 
for queries. 


Options are 
-d 

-P 


Print debugging information. A number after thed determines the level of messages 
printed. 

Use nonstandard port numbers. The default is the standard port number as returned by 
getservbyname(3) for service "domain". T he argument can specify two port numbers 
separated by a slash (/), in which case the first port is that used when contacting remote 
servers and the second one isthe service port bound by the local instance of named. This 
is used mostly for debugging purposes. 

Use an alternate bootfile This is optional and allows you to specify a file with a leading 
dash. 

T race all incoming queries if named has been compiled with qrylog defined. N otethat 
thisoption isdeprecated in favor of the boot file directive options query-log. 

T urns recursion off in the server. Answers can come only from local (primary or 
secondary) zones.Thiscan beused on root servers. N otethat thisoption isdeprecated 
in favor Of the boot file directive options no-recursion. 


Any additional argument is taken asthenameof the bootfile. If multiple boot files are specified, only the last is used. 

The bootfile contains information about where the nameserver is to get its initial data. Lines in the boot file cannot be 
continued on subsequent lines. The following is a small example: 


; boot file for name server 

directory /usr/local/adm/named 
; type domain source host/file backup file 
cache . root.cache 

primary Berkeley.EDU berkeley.edu.zone 
primary 32.128.IN-ADDR.ARPA ucbhosts.rev 

secondary CC.Berkeley.EDU 128.32.137.8 128.32.137.3 cc.zone.bak 
secondary 6.32.128.IN-ADDR.ARPA 128.32.137.8 128.32.137.3 cc.rev.bak 
primary 0.0.127.IN-ADDR.ARPA localhost.rev 



named 



forwarders 10.0.0.78 10.2.0.78 
limit transfers-in 10 
limit datasize 64M 

options forward-only query-log fake-iquery 

The directory line causes the server to change its working directory to the directory specified. This can be important for the 
correct processing of sinclude files in primary zonefiles. 

The cache line specifies that data in root, cache is to be placed in the backup cache. 

Its main use is to specify data such as locations of root domain servers. This cache is not used during normal operation, but is 
used as "hints" to find the current root servers. The file root, cache is in the same format as berkeiey.edu. zone. There can be 
more than one cache file specified. The root, cache file should be retrieved periodically from ftp.rs.internic.net because it 
contains a list of root servers, and this list changes periodically. 

The first sample primary line states that the file berkeiey.edu. zone contains authoritative data for theBerkeiey.EDu zone. The 
file berkeiey.edu. zone contains data in the master file format described in RFC 883. All domain names are relative to the 
origin, in this case, Berkeiey.EDu (see below for a more detailed description). The second primary line states that the file 
ucbhosts.rev containsauthoritativedataforthedomain 32.i28.in-addr.arpa, which isused to translate addresses in network 
128.32 to hostnames. Each master file should begin with an SOA record for the zone (see below). 

The first sample secondary line specifies that all authoritative data under cc.Berkeiey.EDu is to be transferred from the 
nameserver at 128 . 32 . 137 . 8 . If the transfer fails, it tries 128 . 32 . 137.3 and continues trying the addresses, up to ten, listed on 
this line. The secondary copy is also authoritative for the specified domain. The first non-dotted-quad address on this line is 
taken as a filename in which to back up the transferred zone The nameserver loads the zone from this backup file if it exists 
when it boots, providing a complete copy even if the master servers are unreachable Whenever a new copy of the domain is 
received by automatic zone transfer from one of the master servers, this file is updated. If no filename is given, a temporary 
file is used and deleted after each successful zone transfer. This is not recommended because it is a needless waste of 
bandwidth. The second sample secondary line states that the address-to-hostname mapping for the subnet 128 . 32.136 should 
be obtained from the same list of master servers as the previous zone. 

Thetorwarders line specifies the addresses of sitewide servers that will accept recursive queries from other servers. Iftheboot 
file specifies one or more forwarders, then the server sends all queries for data not in the cache to the forwarders first. Each 
forwarder is asked in turn until an answer is returned or the list is exhausted. If no answer is forthcoming from a forwarder, 
the server continues as it would have without the forwarders line uni ess it is in forward-only mode. The forwarding facility is 
useful to cause a large sitewide cache to be generated on a master and to reduce traffic over links to outside servers. It can also 
be used to allow servers to run that do not have direct access to the Internet but want to look up exterior names anyway. 

T he slave line (deprecated) is allowed for backward compatibility. Its meaning is identical to options forward-only. 

T he sortiist line can be used to indicate networks that are to be preferred over other networks. Queries for host addresses 
from hosts on the same network as the server receive responses with local network addresses listed first, then addresses on the 
sort list, and then other addresses. 

T he xf rnets di recti ve (not shown) can beused to implement primitive access control. If this directi ve is given, your 
nameserver only answers zone transfer requests from hosts that are on networks listed in your xf rnets directives. This 
directive may also be given astcpiist for compatibility with older, interim servers. 

The include directive (not shown) can beused to process the contents of some other file as though they appeared in place of 
the include directive. T his is useful if you have a lot of zones or ifyou havelogical groupingsof zones that are maintained by 
different people. The include directive takes one argument, the name of the file whose contents are to be included. N 0 
quotes are necessary around the fi lename. 

Thebogusns di recti ve (not shown) tells BIN D that no queries are to be sent to the specified nameserver addresses (which are 
specified as dotted quads, not as domain names). This is useful when you know that some popular server has bad data in a 
zone or cache, and you want to avoid contamination while the problem is being fixed. 

The limit directive can beused to changeBIN D's internal limits, some of which (datasize, for example) are implemented 
by the system and others (such as transfers-in) by BIN D itself. The number following the limit name can be scaled by 
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postfixing a k, m, or g for kilobytes, megabytes, and gigabytes respectively, datasize's argument sets the process data size 
enforced by the kernel. N otethat not all systems provide a call to implement this; on such systems, the use of thedatasize 
parameter of limit results in a warning message, transfers-in's argument is the number of named-xfer subprocesses that 
BIND will spawn at any onetime, transfers-per-ns's argument is the maximum number of zone transfers to be simulta¬ 
neously initiated to any given remote nameserver. 

The options directive introduces a Boolean specifier that changes the behavior of BIN D. M ore than one option can be 
specified in a single directive. The currently defined options are as follows: no-recursion, which causes Bl N D to answer with 
a referral rather than actual data whenever it receives a query for a name it is not authoritative for. Don't set this on a server 
that is listed in any host's resoiv.conf file, no-fetch-glue keeps BIN D from fetching missing glue when constructing the 
"additional data" section of a response this can be used in conjunction with no-recursion to prevent BIND's cache from ever 
growing in size or becoming corrupted, query-log causes all queries to be logged via sysiog(3). This is a lot of data; don't 
turn it on lightly, forward-only causes the server to query only its forwarders. This option is usually used on a machine that 
wants to run a server but for physical or administrative reasons cannot be given access to the Internet, fake-iquery tells 
BIND to send back a useless and bogus reply to "inverse queries" rather than respond with an error. This is helpful if you 
have a lot of microcomputers or SunO S hosts or both. 

The max-fetch directive (not shown) is allowed for backward compatibility; its meaning is identical to limit transfers-in. 

The master file consists of control information and a list of resource records for objects in the zone of the forms: 

$INCLUDE <f i I e n a me ><o p t _ d o ma i n > 

$0RIGIN <domai n> 

<domai n><opt_111 > <opt_cI ass><type><resource_record_data> 

domai n is . for root, @ for the current origin, or a standard domain name. If domai n is a standard domain name that does not 
end with ., the current origin is appended to the domain. Domain namesending with . are unmodified. The opt _ domai n 
field is used to define an origin for the data in an included file. It is equivalent to placing a sorigin statement before the first 
line of the included file. The field is optional. N either the opt _ d o ma i n field nor sorigin statements in the included file modify 
the current origin for this file T heopt 111 field is an optional integer number for the time-to-live field. It defaults to 0 , 
meaningtheminimum value specified in theSOA record for thezone. T he 0 pt _ c 1 ass field isthe object address type; 
currently only one type is supported, 1 n, for objects connected to the D ARP A Internet. The type field contains one of the 
following tokens; the data expected in the res our ce_ record, data field is in parentheses: 

a A host address (dotted quad). 

ns An authoritative nameserver (domain). 

mx A mail exchanger (domain), preceded by a preference value (0..32767) with lower 

numeric values representing higher logical preferences. 
cname Thecanonical namefor an alias (domain). 

soa M arks the start of a zone of authority (domain of originating host, domain address of 

maintained a serial number and the following parametersin seconds: refresh, retry, 
expire, and minimum TTL (see RFC 883)). 
nuli A null resource record (no format or data). 

rp A responsible person for somedomain narne(maiibox, TXT-referrai). 

ptr A domain name pointer (domain). 

hinfo H ost information (cpu_type, os_type). 

Resource records usually end at the end of a line but may be continued across lines between opening and closing parentheses. 
Comments are introduced by semicolons and continue to the end of the line. 

N otethat there are other resource record types, not shown here. You should consult the BIN D OperationsGU IDe(BOG) 
for the complete list. Some resource record types may have been standardized in newer RFC s but not yet implemented in 
this version of BIN D. 

Each master zone file should begin with an SOA record for the zone. A sample SO A record follows: 



named 



@ IN SOA ucbvax.Berkeley.EDU. rwh.ucbvax.Berkeley.EDU. ( 

1989020501 ; serial 
10800 ; refresh 
3600 ; retry 
3600000 ; expire 
86400 ) ; minimum 

The SO A specifies a serial number, which should be changed each time the master file is changed. N ote that the serial 
number can be given as a dotted number, but this is a very unwise thing to do because the translation to normal integers is 
via concatenation rather than multiplication and addition. You can spell out theyear, month, day of month, and 0..99 
version number and still fit inside the unsigned 32-bit size of this field. It's true that we will have to rethink this strategy in 
theyear 4294, but we're not worried about it. Secondary servers check the serial number at intervals specified by the refresh 
time in seconds; if the serial number changes, a zone transfer is done to load the new data. If a master server cannot be 
contacted when a refresh is due, the retry time specifies the interval at which refreshes should be attempted. If a master server 
cannot be contacted within the interval given by the expire time, all data from the zone is discarded by secondary servers. 
The minimum value is the time-to-live(TTL) used by records in the file with no explicit time-to-live value. 


NOTES 


The boot file directives domain and suffixes have been obsoleted by a more useful resolver-based implementation of suffixing 
for partially qualified domain names. The prior mechanisms could fail under a number of situations, especially when then 
local nameserver did not have complete information. 


T he following signals have the specified effect when sent to the server process using the kiii(l) command: 


SIGHUP 


SIGINT 

SIGIOT 


SIGSYS 

SIGTERM 

SIGUSR1 

SIGUSR2 

SIGWINCH 


C auses server to read named.boot and reload the database. If the server isbuiltwith the 
forced reload compi le-time option, then sighup also causes the server to check the serial 
number on all secondary zones. U sually, the serial numbers are only checked at the 
SOA-specified intervals. 

Dumps the current database and cache to /var/tmp/namedjiump.db. 

Dumps statistics data into /var/tmp/named. stats if the server is compiled with -dstats. 
Statistics data is appended to the file Some systems use sigabrt rather than sigiot for 
this 

Dumps the profiling data in /var/tmp if the server is compi led with profiling (the server 
forks, changes directories, and exits). 

Dumps the primary and secondary database files. Used to save modified data on 
shutdown if theserver iscompiled with dynamic updating enabled. 

T urns on debugging; each sigusri increments debug level (sigemt on older systems 
without sigusri). 

T urns off debugging completely (sigfpe on older systems without sigusr 2 ). 

Toggles logging of all incoming queries via sysiog(3) (requires server to have been built 
with theQRYLOG option). 


FILES 

/etc/named.boot 
/etc/named.pid 
/var/run/named.pid 
/var/tmp/named_dunp.db 
/var/tmp/named.run 
/var/tmp/named.stats 


N ameserver configuration boot file 
The process ID (on older systems) 
The process ID (on newer systems) 
D ump of the nameserver database 
D ebug output 
N ameserver statistics data 
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SEE ALSO 

kill(l), gethostbyname(3), signal(2), nesolver(3), resolver(5), hostname(7), RFC 882, RFC 883, RFC 973, RFC 974, RFC 
1033, RFC 1034, RFC 1035, RFC 1123, NameServer0perationsGUIDeforBIND 

20Junel995 

named.reload 

named. reload— C ause the nameserver to synchronize its database. 

DESCRIPTION 

This command sendsasiGHUP to the running nameserver. This signal is documented in named(8). 

BUGS 

It does not check to see if the nameserver is actually running and could use a stale pi d cache file, which may result in the 
death of an unrelated process. 

SEE ALSO 

named(8), named.restart(8) 

26Junel993 


named.restart 

named. restart— Stop and restart the nameserver. 

DESCRIPTION 

This command sendsasiGKiu. to the running nameserver and then starts a new one. 

BUGS 

It does not check to see if the nameserver is actually running and could use a stale pi d cache file, which may result in the 
death of an unrelated process. 

It does not wait after killing the old server before starting a new one. Because the server could take some time to die and the 
new one experiences a fatal error if the old one isn't gone by the time it starts you can be left in a situation where you have 
no nameserver at all. 

SEE ALSO 

named(8), named.reload(8) 

26Junel993 


ndc 

ndc — N amedaemon control interface. 

SYNOPSIS 


ndc directive [ ... ] 



netstat 



DESCRIPTION 

This command al lows the nameserver administrator to send various signals to the nameserver or to restart it. Zero or more 
directives may be given from the following list: 

status D i splays the current status of named as shown by ps(l). 

dumpdb C auses named to dump its database and cache to /var/tmp/named_dump.db (uses the INT 

signal.) 

reload C auses named to check the serial numbers of all primary and secondary zones and to 

reload those that have changed (usestheHUP signal.) 

stats Causes named to dump itSStatistiCStO /var/tmp/named.stats (usestheiOT Or ABRT Signal.) 

trace Causes named to increment its "tracing I e/el" by one. W henever the tracing level is 

nonzero, trace information iswritten to /var/tmp/named.run. H igher tracing levels result 
in more detailed information (uses the usri signal). 

notrace Causes named to Set its"tracing level'' to zero, closing /var/tmp/named.run if it isopen 

(uses the usr 2 signal). 

queryiog Causes named to toggle the "query logging" feature, which results in asysiog(3) of each 

incoming query (uses the winch signal). N otethat query logging consumes quite a lot of 
log file space. This directive may also be given asqryiog. 

start Causes named to be started as long as it isn't already running, 

stop Causes named to be stopped if it is running, 

restart Causes named to be killed and restarted. 

BUGS 

Arguments to named are not preserved by restart or known by start. Some mechanism for controlling the parameters and 
environment should exist. 

Implemented as a sh(l) script. 

AUTHOR 

Paul Vixie (Internet Software Consortium) 

SEE ALSO 

named(8), named.reload(8), named.restart(8) 

27 N ovember 1994 


netstat 

netstat— D isplay active network connections 

SYNOPSIS 

netstat [[-a | [-t | -u | -w] ] [-n | -o] | -x] [ - c] 
netstat -r [-c] [-n] 
netstat -v 

DESCRIPTION 

netstat di splays the status of network connections on either TCP, UD P, or RAW sockets to the system. By default, netstat 
only displays status on thoseTCP sockets that are not in the listen state (that is, connections to active processes). T o obtain 
information about the kernel routing table, netstat may be invoked with the option -r. A listing of internal U N IX 
connections can beobtained by invoking netstat with the option -x. 
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netstat's display includes the following information for each socket: 


Proto 

Recv-Q 

Send-Q 

Local Address 


Foreign Address 

(State) 

ESTABLISHED 
SYN SENT 
SYN RECV 
FIN WAIT1 
FIN WAIT2 
TIME WAIT 
CLOSED 
CLOSE WAIT 
LAST ACK 
LISTEN 
UNKNOWN 


The protocol (either TCP or U D P) used by the socket. 

The count of bytes not copied by the user program connected to this socket. 

T he count of bytes not acknowledged by the remote host. 

The local address (local hostname) and port number of the socket. U nlessthe -n switch 
is given, thesocket address is resolved to its canonical hostname, and the port number is 
transl ated i nto th e co rrespo n d i n g servi ce n am e. 

T he remote address (remote hostname) and port number of the socket. As with the local 
address: port, the -n switch turns off hostname and service name resolution. 

The state of thesocket. Because there are no states in RAW and usually no states used in 
UD P, this row may be left blank. Usually, this can be one of several values: 

Thesocket has an established connection. 

Thesocket is actively attempting to establish a connection. 

The connection is being initialized. 

The socket is closed, and the connection is shutting down. 

Connection is closed, and thesocket is waiting for a shutdown from the remote end. 
Thesocket is waiting after close for remote shutdown re-transmission. 

Thesocket is not being used. 

The remote end has shut down, waiti ng for the socket to close. 

The remote end shut down, and thesocket is closed. Waiting for acknowledgment. 
Thesocket is listening for incoming connections. 

The state of thesocket is unknown. 


If netstat is invoked with theoption -o, additional information isdisplayed after the state info. This information is shown 
like this: keyword (tim^backoff) and an optional asterisk. The keyword shows the state of the timer belonging to thesocket, 
the time displayed (in seconds) ishow long it will take the timer to expire, the backoff value indicates the current retry count 
for data transmission, and the asterisk indicates that this timer is in the expiration queue. The latter might be removed in 
future but is helpful for debuggi ng the T C P-C ode for now. 

Invoked with theoption -x, netstat displays a list of all active U N IX internal communication sockets, 
netstat 's display includes the following information for each socket: 


Proto 

The protocol (usually UN IX) used by thesocket. 

RefCnt 

T he reference count (attached processes via this socket). 

Flags 

The only known flag to meisso accepton (displayed as acc) ; otherwise, left blank, 
so accepton is used on unconnected sockets if their corresponding processes are waiting 
for a connect request. 

Type 

T here are several types of socket access: 

SOCK DGRAM 

The socket is used in Datagram (connectionless) mode. 

SOCK STREAM 

This is a stream (connection) socket. 

SOCK RAW 

The socket is used as a raw socket. 

SOCK RDM 

T h i s o n e serves rel i ab 1 y d el i vered m essages. 

SOCK SEQPACKET 

This is a sequential packet socket. 

SOCK PACKET 

This socket type is used as a Linux-specific way to get packets at the dev (kernel) level. It 
is assumed to be used to write things such as RARP (Reverse Address Resolution 
Protocol) and similarthingson theuser level. 

UNKNOWN 

Who ever knows, what future will bring; just fill in here.:-) 

State 

Thisfield will contain one of the following keywords: 

FREE 

T he socket is not allocated. 
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LISTENING 

UNCONNECTED 

CONNECTING 

CONNECTED 

DISCONNECTING 

UNKNOWN 

Path 


T he socket is listening for a connection request. 

T he socket is not connected to another one. 

T he socket is about to establish a connection. 

The socket is connected. 

The socket is disconnecting. 

This state should never happen. 

This displays the pathname that the correspondi ng processes attached to the socket. 


The network routing table (invoked with netstat -r) shows up the following information: 

Destination net/address The destination address of a resolved host or hand-entered network is displayed. U nless 

the option -n is given, the hosts or nets are resolved. An entry named default shows up 
the default route for the kernel. 

Gateway address If there is no asterisk (*) displayed, any data is routed to the dedicated gateway. 

Flags Possible routing flags are 

u This route is usable. 

g Destination isagateway. 

h Destination isa host entry. 

n Destination isaNet entry. 

r Route will be reinstated after timeout. 

d This one is created dynamically (by redirection). 

m Thisoneismodified dynamically (by redirection). 


RefCnt 
Use 
I face 

OPTIONS 

-a 

-c 

-n 

-o 

-r 

-t 

-u 

-v 

-w 

-X 


Reference count for this route. 

How many times this route was used yet. 

T his is the name of the interface where this route belongs. 


D isplay information about all Internet sockets, such asTCP, UD P, and RAW, 
including those sockets that are listening only. 

Generate a continuous listing of network status: network status is displayed every second 
until the program is interrupted. 

Causes netstat not to resolve hostnames and service names when displaying remote and 
local address and port information. 

D isplay timer states, expiration times, and backoff state. 

D isplay kernel routing table. 

D isplay information about TCP sockets only, including those that are listening. 

D isplay information about U D P sockets only. 

Print version information. 

D isplay information about raw sockets. 

D isplay information about UNIX domain sockets. 


FILES 


/proc/net/tcp 

/proc/net/udp 

/proc/net/raw 

/proc/net/unix 


TCP socket information 
UDP socket information 
RAW socket information 
UN IX domain socket information 
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/proc/net/route Kernel routing information 

/etc/services T he services translation 

BUGS 

N one reported yet (5/20/93). 

AUTHORS 

Thenetstat user interface was written by Fred Baumgarten (dc6iq@insui .etec.uni-karisruhe.de). The man page is basically 
by M att W elsh (mdw@tc.cornell.edu). 

Cohesive Systems 20 M ay 1993 


makeactive, makehistory,newsrequeue 

makeactive, makehistory, newsrequeue —TOOlstO recover Usenet databases 

SYNOPSIS 

makeactive [ -m ][-o ] 

makehistory [ -b ][-f filename ][-i ][-n ][-o ][-r ][-s size ] 

[ -T tmpdi r ][-u [ - v] ] 

newsrequeue [ -a active ][-h history ][-d days ][-1 ][-n newsfeeds ] [ i n p ut ] 

DESCRIPTION 

makeactive invokes tind(l) to get a list of all directories in the news spool tree, /news/spool. It discards directories named 
lost+tound as well as those that have a period in them. It scans all other directories for all-numeric filenames and determines 
the highest and lowest number. The program's output is a set of active(5) file lines. Becausethereisno way to know if a 
group is moderated or disabled, the fourth field of all entries is y. Also, mid-level directories that aren't newsgroups are also 
created as newsgroups with no entries. (For example, there is a comp, sources, unix group, but no comp, sources.) 

If the -o flag is used, makeactive reads an existing active file for the list of group names and just renumber all groups. It 
preserves the fourth field of the active file if one is present. This is analogous to thectiinnd(8) renumber command, except 
that innd(8) should be throttled or not running. Do not use this flag with output redirected to the standard active file! 

If the -m flag is given, then makeactive attempts to adjust the highest and lowest article numbers wherever possible. If articles 
are found in a newsgroup, the numbers reflect what was found. If no articles are found in a newsgroup, the high number 
from the old file is kept, and the low number is set to one more than the high number. This flag may only be used if the -o 
flag is used. 

makeactive exits with nonzero status if any problems occur. A typical way to use the program is with the following /bin/sh 
commands: 

ctlinnd throttle "Rebuilding active file" 

TEMP=${TMPDIR-/tmp}/act$$ 
if [ -f /var/lib/news/active ] ; then 
if makeactive -o >${TEMP} ; then 
mv ${TEMP} /var/lib/news/active 
fi 

else 

if makeactive >${TEMP} ; then 

# Edit to restore moderated 

# and aliased groups. 

mv ${TEMP} /var/lib/news/active 
fi 
fi 

ctlinnd reload active "New active file" 
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makehistory rebui Ids the history (5) text file and the associated dbz(3) database. The default name of the text file is 
/news/iib/history; to specify a different name usethe-f flag, makehistory scans the active(5) file to determinewhich 
newsgroup directories within the spool directory, /news/spool, should be scanned. (If a group is removed, but its spool 
directory still exists, makehistory ignores it.) The program reads each file found and writes a history linefor it. If the -b flag 
is used, then makehistory removes any articles that do not have valid M essage-ID headers in them. 

After the text file is written, makehistory builds the dbz database. If the -t flag is used, then the database files are named 
tile, dir and tiie.pag. If the-f flag is not used, then a temporary link to the name history, n is made and thedatabasefiles 
are written as history, n.pag and history, n. dir. If the -o flag is used, then the link is not made and any existing history files 
are overwritten. If the old database exists, makehistory uses it to determine the size of the new database. T o ignore the old 
database, usethe -i flag. U sing the -o flag implies the -i flag. The program also ignores any old database if the -s flag isused 
to specify the approximate number of entries in the new database. Accurately specifying the size is an optimization that 
creates a more efficient database. (The size should be the estimated a/entual size of the file typically the size of the old file.) 
For more information, see the discussion of dbzfresh and dbzsize in dbz(3). 

If the -u flag is given, then makehistory assumes that innd is running. It pauses the server while scanning and then sends 
addhist commands (see ctiinnd(8)) to the server for any article that is not found in the dbz database. The command 
makehistory -bu is useful after a system crash to delete any mangled articles and bring the article database back into a more 
consistent state. If the -v flag isused with the -u flag, then makehistory puts a copy of all added lines on its standard output. 

T o scan the spool directory without rebuilding the dbz files, use the -n flag. If used with -u, the server is not paused while 
scanning. To just build the dbz files from an existing text file, use the -r flag. The -i or -s flags can be useful if there are no 
valid dbz files to use. A typical way to usethisprogram iswith the following / bin/sh commands: 

ctlinnd throttle "Rebuilding history file" 
cd /news/lib 

if makehistory -n -f history.n ; then 
else 

echo Error creating history file! 
exit 1 
fi 

# The following line can be used to retain expired history. 

# It is not necessary for the history file to be sorted. 

# awk 'NF==2 { print; }' chistory »history.n 

# View history file for mistakes. 

if makehistory -r -s 'wc -1 <history' -f history.n; then 

mv history.n history 

mv history.n.dir history.dir 

mv history.n.pag history.pag 

fi 

ctlinnd go 11 

makehistory needs to create a temporary file that contains one line for each article it finds, which can become very large. This 
file is created in the /tmp directory. The tmpdir environment variable may be used to specify a different directory. Alterna¬ 
tively, the-T flag may be used to specify a temporary directory. In addition, the sort(l) that is invoked during the build 
writes large temporary files (often to /var/tmp, but see your system man pages). If the-T flag isused, then the flag and its 
value are passed to sort. 0 n most systems, this changes the temporary directory that sort uses. If used, this flag and its value 
are passed on to the sort (1) command that is invoked during the build. 

makehistory does not handle symbolic links If the news spool area is split across multiple partitions, the following commands 
should probably be run before the database is regenerated: 

cd /news/spool 

find . -type 1 -name '[1-9]*' -print \ xargs -t rm 


M akesureto run thecommand on all the appropriate partitions! 
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newsrequeue can be used to rewrite batchfilesafter a system crash. It operates in two modes. In the first mode it first reads 
theacti ve and newsf eeds (5) filesto determine where the different newsgroups are to be distributed. T o specify alternate 
locationsfor these files, use the -a or-n flags. It then opens the hi story database. T o specify a different file, use the -h flag. 

Once the files are opened, newsrequeue reads from the specified input file or standard input if no file is specified. Each line 
should haveasingleM essage-ID, surrounded in angle brackets; any other text on thelineisignored. For example the 
history file (or a trailing subset of it) is acceptable input to the program operating in this mode. If the-d flag is used, then 
only articles that were received within thespecified number of days areprocessed. 

newsrequeue uses the first two fields of the newsteed entry— the sitename and the excludes field and the patterns and 
distribs field. It ignores all flags in the third field except for the n field and also ignores thefourth field altogether. 

The second mode is used if the -1 flag is used. In this mode, it reads from thespecified input file or standard input if no file 
is specified. Each line should look like an mnd log entry. It parses entries for accepted articles, looks up the M essage-ID in 
the history database to get thefilename, and then scans the list of sites. 

In either mode the output of newsrequeue consists of one line for each article that should be forwarded. Each such line 
containstheM essage-ID, thefilename, and the list of sites that should receive the article. The output is suitable for piping 
into filechan(8). 

HISTORY 

W ritten by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

active(5), ctlinnd(8), dbz(3), filechan(8), history(5), innd(8), newsfeeds(5) 

news.daily 

news.daily— D o regular U senet system administration 

SYNOPSIS 

news.daily [ key wo rd ... ] 

innwatch [ -t sleeptime ][-f controlfile ] [ -1 logfile ] 
expirerm file 

inncheck [ -v ][-pedantic ] [ - p e r ms [ -fix ]][-noperms ][file... ] 

DESCRIPTION 

news, daily performs a number of important U senet administrative functions. T his includes producing a status report, 
removing old news articles, processing log files, rotating the archived log files, renumbering the active fi le, removing any old 
socket files found in the firewall directory, and collecting the output. This program should be run under the news 
administrator's ID, not as root. 

By default, news, daily performs all its functions and mails the output to the news administrator, Usenet. By specifying 
keywords on the command line, it is possible to modify the functions performed, as well as change the arguments given to 
expire(8) and expireover(8). 

news, daily should be run once a day, typically out of cron(8). It may be run more often, but such invocations should at least 
use the norotate keyword to prevent the log files from being processed and rotated too fast. 

Theshiock(l) program isused to prevent simultaneous executions. 

The following keywords may be used: 

deiayrm T his usesthe -z flag when invoking expire and expireover. The names of articles to be 

removed are written to a temporary file and then removed after expiration by calling 
expirerm. 
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nostat T his keyword disables the status report generated by innstat (see newsiog(8)). W ithout 

this keyword, the status report is the first function performed, just prior to obtaining the 
news.daily lock. 

noexpire By default, expire isinvoked to remove old newsarticles. Using thiskeyword disables 

this function. 

noexplog expire usually appends information to /var/log/news/expire.log (see newslog(5)). Using 

thiskeyword causes the expire output to be handled as part of news, daily's output. It 
has no effect if the noexpire keyword is used. 

tiags= 1 expire\args 1 By default, expire isinvoked with the an argument of -vi. Using this keyword changes 

the arguments to those specified. Be careful to use quotes if multiple arguments are 
needed. Thiskeyword has no effect if the noexpire keyword is used. 

noiogs After expiration, scaniogs(8) isinvoked to process the log files. Using this keyword 

disables all log processing functions. 

norotate Bydefault, log processing includes rotating and cleaning out log files. Usingthis 

keyword disables the rotating and cleaning aspect of the log processing. The log files are 
only scanned for information and no contents are altered. Thiskeyword hasno effect if 
the noiogs keyword is used. 

norenumber Thiskeyword disablesthe ctimnd(8) renumber operation. U sually, the low watermark 

for all newsgroups(seeactive(5)) is reset. 

norm By default, any socket ctiinnd socket that has not been modified for two days is 

removed. Using thiskeyword disables this function. 

nomaii news.daily usually sends a mail message containing the results to the administrator. 

Using thiskeyword causes this message to be sent to stdout and stderr instead. Usually, 
all utilities invoked by the script have their stdout and stderr redirected intoafile. Ifthe 
file is empty, no message is sent. 

expireover T he expireover program is called after expiration to purge the overview databases. 

expireovertiags= 1 expireovernargs 1 If the expireover keyword is used, this keyword may be used to specify the flags to be 

passed to expireover. If thedeiayrm keyword is used, then the default value is -z and the 
list of deleted files; otherwise, the default value is -s. 

/fuii/path The program specified by the given path is executed just before any expiration is done. 

A typical useisto specify an alternate expiration program and use the noexpire keyword. 
M ultiple programs may be specified; they are invoked in order. 


The norotate keyword is passed on to scaniogs if it isinvoked. expire™ is a script that removes a list of files. The specified 
file lists the files. It is sorted and then fed into a pipeline responsible for doing the removal, usually fast rm(8). If there seemed 
to be a problem removing the files, then mail is sent to the news administrator. If there were no problems, then file is 
renamed to /var/iog/news/expire.iist where it is kept (for safety) until the next day's expiration. 

innwatch is a script that can be started at news boot time. It periodically— every si eepti me seconds— examines the load 
average and the number of free blocks and inodes on the spool partition, as described by its control file, innwatch. cti(5). If 
the load gets too high or the disk gets too full, it throttles the server. W hen the condition restores, it unblocks the server. In 
addition, on each passthrough the loop, it checks the specified log file to see if it has been modified and sends mail to the 
news administrator if so. It is usually a good idea to set this to thesysiog(3) file that receives critical news messages. U pon 
receipt of an interrupt signal, innwatch reports its status in the file/news/iib/innwatch.status. 

inncheck isa peri(l) script that verifies the syntax and permissions of all I nterN etN ews configuration files. If no files are 
specified, it checks all files. A filename may be followed by an equal sign and a path to indicate the path name to use for the 
file. For example newsteeds=/tmp/nt checks the syntax of a new newsfeeds(5) without requiring it to be installed. If the -v 
flag is used, it prints status information as it checks each file If the -pedantic flag is used, it checks the files for omissions that 
are not strictly errors but might indicate a configu rati on erro r. 

If any file is specified, only the permissions on those files are checked. The -noperms flag suppresses this check. If the -perms 
flag is used, the script verifies the ownership and permissions of all files. The-fix flag can also be used so that the output can 
be executed as a shell script. 
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HISTORY 

news, daily and this manual page were written by Landon Curt N oil (chongo@toad.com) and Rich $alz (rsaiz@uunet.uu.net). 
inncheck was written by Brendan Kehoe(brendan@cs. widener.edu) and Rich, 
innwatch W3S written by M ike C ooper (mcooper@usc.edu) and (kre@munnari.oz.au). 

SEE ALSO 

active(5), ctlinnd(8), expire(8), fastrm(8), newslog(5), newslog(8), innwatch.ctl(5), shlock(l) 

newslog 

newsiog— M aintenance of Usenet log files 

SYNOPSIS 

scanlogs [ norotate ][nonn ] 
writelog name text... 
innstat 

tally.unwanted 
tally.control 
innlog.awk 

DESCRIPTION 

scanlogs summarizes the information recorded in the inn log files (see newsiog(5)). By default, it also rotates and cleans out 
the logs. It is usually invoked by the news. daiiy(8) script. 

The following keywords are accepted: 

norotate Using this keyword disables the rotating and cleaning aspect ofthe log processing: 

Thelogs files are only scanned for information and no contents are altered, 
nonn Usually, thenn log file is scanned and rotated. Using this keyword disablesthis 

function. 

If scanlogs is invoked more than once a day, the norotate keyword should be used to prevent premature log cleaning. 

The writeiog script is used to write a log entry or send it as mail. The name parameter specifies the name of the log file where 
the entry should be written. If it is the word man, then the entry is mailed to the news administrator, Usenet. The data that 
is written or sent consists of the text given on the command line, followed by standard input indented by four spaces. 
shiock(l) isused to avoid simultaneous updates to a si ngle log file 

T he innstat script prints a snapshot of the inn system. It displays the operating mode of the server, as well as disk usage and 
the status of all log and lock fi les. 

The rest of the scripts described here are usually invoked by scanlogs. They parse log files that are described in newsiog(5) 
and the server's article log fi le described in innd(8). 

tally, unwanted script parses the article log fileto update the cumulative list of articles posted to unwanted newsgroups, 
unwanted.log. 

tally.control reads its standard input, which should bethenewgroup.log and rmgroup.log log files. It updatesthecumulative 
list of newsgroup creations and deletions, control, log. 

innlog.awk is an awk(l) script that summarizes the activity that innd and nnrpd(8) report to sysiog. 

HISTORY 

W ritten by Landon Curt N oil (chongo@toad.com) and Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 
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SEE ALSO 

innd(8) newslog(5), news.daily(8), nnrpd(8) 

nfsd 

nfsd— N FS service daemon. 

SYNOPSIS 

/usr/etc/rpc.nfsd [\-f\exports-file\][\-dhnprv\] 

[ \ - - debug!][\--exports-file=f i I e\] [\- - help\] 

[\- - allow-non-root\][\--re-export\][\- -version\] 

DESCRIPTION 

The nfsd program i s an NFS service daemon that handles client filesystem requests. U nlike nfsd on some other systems, nfsd 
operates as a normal user-level process. The server also differs from other N FS server implementations in that it mounts an 
entire file hierarchy not limited by the boundaries of physical filesystems. The implementation allows the clients read-only or 
read-write access to the file hierarchy of the server machine. 

T he mountd program starts an ancillary user-level mount daemon. 

OPTIONS 

-f or - -exports-file 

-d Or - -debug 
-h Or - -help 
-n Or --allow-non-root 

-p Or - -promiscueus 
-r Or - - re-export 


-v Or - -version 

SEE ALSO 

exports(5), mountd(8), ugidd(8C) 

AUTHORS 

M ark Shand wrote the original unfsd. Don Becker extended unfsd to support authentication and allow read-write access and 
called it hnfs. Rick Sladkey added host matching, showmount -e support, mountd authentication, inetd support, and all the 
portability and configuration code. 

13 October 1993 

nnrpd 

nnrpd— N N T P server for on-campus hosts. 


This option specifies the exports file, listing the clients that this server is prepared to 
serve and parameters to apply to each such mount (see exports(5)). By default, exports 
are read from /etc/exports. 

Log each transaction verbosely to thesysiog. 

Provide a short help summary. 

Allow incoming N FS requests to be honored even if the/ do not originate from reserved 
IP porta Some older N FS client implementations require this Some newer N FS client 
implementations don't believein reserved port checking. 

Put the server into promiscuous mode where it serves any host on the network. 

Allow imported N FS filesystems to be exported. This can be used to turn a machine 
into an N FS multiplier. Caution should be used when re-exporting loopback N FS 
mounts because re-entering the mount point results in deadlock between theN FS client 
and the NFS server. 

Report the current version number of the program. 
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SYNOPSIS 

nnrpd [ -r reason ][-s title padding ][-S host ][-t ] 

DESCRIPTION 

nnrpd isan N NTP server for newsreaders. It accepts commands on its standard input and responds on its standard output. 

It is usually invoked by innd(8) with those descriptors attached to a remote client connection. 

If the -r flag is used, then nnrpd rejects the incoming connection giving reason as the text. Thisflag isused by innd when it is 
paused or throttled. 

Unlike innd, nnrpd supports all N NTP commands for user-oriented reading and posting. 

nnrpd uses the nnrp.access(5) fileto control who is authorized to access the U sen et database. It also rejects connections if the 
load average isgreaterthan 16. 

As each command is received, nnrpd tries to change its argv array so that ps(l) prints the command being executed. To get a 
full display, the-s flag may be used with a long string as its argument, which is overwritten when the program changes its 
title. 

On exit, nnrpd reports usage statistics through sysiog(3). 

If the-t flag isused, all client commands and initial responses are traced by reporting them in sysiog. Thisflag is set by innd 
under the control of the ctiinnd(8) trace command and is toggled upon receipt of asiGHUP; seesignai(2). 

If the-s flag isused, all postings are forwarded to the specified host, which should be the master N NTP server. Thisflag is 
set by innd if it is started with the-s flag. 

nnrpd can accept multimedia postings that follow the M I M E standard as long as such postings are also acceptable as SM TP 
messages. See the discussion of the M IM E headers in inn.conf(5). 

PROTOCOL DIFFERENCES 

nnrpd implements the N NTP commands defined in RFC 977 with the foil owing differences: 

■ Theihave command is not implemented. Users should be using the post command to post articles. 

■ The slave command is not implemented. This command has never been fully defined. 

■ The list Command may be followed by the optional word active, times, distributions, dist rib. pats, newsgroups, or 
overview, fmt to get a list of when newsgroups where created, a list of valid distributions, a file specifying default 
distribution patterns, a one-per-line description of the current set of newsgroups, or a listing of the overview. fmt(5) file. 
Thecommand list active is equivalent to the list command. Thisisacommon extension. 

■ Thexhdr, authinfo user, and authinto pass commands are implemented. T hese are based on the reference U NIX 
implementation; no other documentation is available. 

■ A new command, xpat header range ] MessageiD pat [morepat ...], is provided. T he first argument is the case-in sensitive 
name of the header to be searched. The second argument is either an article range or a single M essage-l D as specified in 
RFC 977. The third argument is a wiidmat(3)-style pattern; if there are additional arguments, they are joined together 
separated by a single space to form the complete pattern. This command issimilarto thexhdr command. It returns a 221 
response code, followed by thetext responseof all article numbers that match the pattern. 

■ T he ustgroup group command isprovided. Thisisacomment extension. It is equivalent to thegroup command, except 
that the reply is a multi-line response containing the list of all article numbers in the group. 

■ T he xgtitie [group] command isprovided. This extension isused by ANU-N ews. It returns a 282 reply code, followed 
by a one-line description of all newsgroups that match the pattern. The default is the current group. 

■ Thexover [range] command is provided. It returns a 224 reply code, followed by the overview data for the specified 
range; the default is to return the data for the current article. 

■ Thexpath MessageiD command isprovided; see innd(8). 

■ The date command isprovided; this is based on the draft N NTP protocol revision. It returns a one-line response code 
of 111 followed by theGMT date and time on the server in the form YYYYMMDDh turns. 
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HISTORY 

W ritten by Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. Overview support added by Rob Robertston 
(rob@vioiet.berkeiey.edu) and Rich in January 1993. 

SEE ALSO 

ctlinnd(8), innd(8), inn.conf(5), nnrp.access(5), signal(2), wildmat(3) 

nntpsend 

nntpsend — Send U senet articles to remote site. 

SYNOPSIS 

nntpsend [ -d ][-p ][-r ][-S ][-s size ][-t timeout ] 

[ -T t i me I i mi t ] [s i t ena me f qdn ] ... 

DESCRIPTION 

nntpsend is a front end that i nvokes innxmit(l) to send U senet articles to a remote N N T P site 

The sites to be fed may be specified by givings i t ena me f qdn pairs on the command line. If no such pairs are given, nntpsend 
defaults to the information given in the nntpsend. cti(5) configfile. 

T he s i t ena me should be the name of the site as specified in the newsfeeds(5) file Thefqdn should bethehostname 
or IP address of the remote site. An innxmit is launched for sites with queued news. All innxmit processes are 
spawned in the background and the script waits for them all to finish before returning. Output is sent to the file 
/ var/iog/news/nntpsend. log. T o avoid overwhelming the local system, nntpsend waits five seconds before spawning 
each child. The flag -a is always given as a flag to innxmit. 

nntpsend expects that the batchfilefor a site is named /news/spooi/out .going/si t ena me . T o prevent batchfile corruption, 
shiock(l) is used to "lock" these files. 

The-p, -r, -s, -t, and -t flags are passed on to the child innxmit program. N otethat if the -p flag is used then no connection 
is made and no articles are fed to the remote site. It is useful to havecron(8) invoke nntpsend with this flag in case a site 
cannot be reached for an extended period of time 

If the -s flag is used, then shrinkfiie(l) is invoked to perform a tail truncation on the batchfile and the flag is passed to it. 

When si t ena me f qdn pai rs are gi ven on the command line, any flags given on the command completely describe how innxmit 
and shrinkt iie operate. W hen no such pairs are given on thecommand line then the information found in nntpsend.cti 
becomes the default flags for that site. Any flags given on the command line override the default flags for the site. 

For example, with the following control file 

nsavax:erehwon.nsavax.gov::-S -t60 
group70:group70.org:: 
walldrug:walldrug.com:1m:-T1800 -t300 

Thecommand 

nntpsend 

will result in thefollowing: 

Sitename Truncation Innxmit flags 

nsavax (none) -a -S -t60 

group70 (none) -a -t180 

walldrug 1m -a -T1800 -t300 
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The command 

nntpsend -d -T1200 

will result in thefollowing: 

Sitename Truncation Innxmit flags 

nsavax (none) -a -d -S -T1200 -t60 

group70 (none) -a -d -T1200 -t180 

walldrug 1m -a -d -T1200 -t300 

The command 

nntpsend -s 5m -T1200 nsavax erehwon.nsavax.gov group70 group70.org 

will result in thefollowing: 

Sitename Truncation Innxmit flags 

nsavax 5m -a -T1200 -t180 

group70 5m -a -T1200 -1180 

Remember that -a is always given, and -t defaults to iso. 

HISTORY 

Written by Landon Curt N oil (chongo@toad.com) and Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

innxmit(l), newsfeeds(5), nntpsend.ctl(5), shrinkfile(l) 

nslookup 

nsiookup — Q uery I nternet nameservers interactively. 

SYNOPSIS 

nslookup [ -option ... ] [ host-to-fi nd j -[server ]] 

DESCRIPTION 

nslookup is a program to query Internet domain nameservers. nslookup has two modes: interactive and non-interactive. 
Interactive mode allows the user to query nameservers for information about various hosts and domains or to print a list of 
hosts in a domain. Non-interactive mode is used to print just the name and requested information for a host or domain. 

ARGUMENTS 

Interactive mode is entered in thefollowing cases: 

■ W hen no arguments are given (the default nameserver is used) 

■ When the first argument is a hyphen (-) and the second argument is the hostname or Internet address of a nameserver 

N on-interactive mode is used when the name or Internet address of the host to be looked up is given as the first argument. 

T he optional second argument specifies the host name or address of a nameserver. 

The options listed under the set command can be specified in the .nsiookuprc file in the user's home directory if they are 
listed one per line. Options can also be specified on the command line if they precede the arguments and are prefixed with a 
hyphen. For example, to change the default query type to host information, and the initial timeout to 10 seconds, type: 



nslookup -query=hinfo -timeout=10 



nslookup 


server domai n, lserver domai n 


INTERACTIVE COMMANDS 

Commands may be interrupted at any time by typing Ctrl+C. T o exit, type C trl+D (EOF) or type exit. The command-line 
length must be less than 256 characters. T o treat a built-in command as a hostname, precede it with an escape character (n). 

N otethat an unrecognized command is interpreted as a hostname. 

host [server ] Look up information for host using the current default server or using s er m if 

specified. If hos t is an I nternet address and the query type is a or ptr, the name of the 
host is returned. If host is a name and does not have a trailing period, the default 
domain name is appended to the name. (This behavior depends on th e state of the 
set options domain, srchlist, defname, and search). T 0 look up a host not in the Current 
domain, append a period to the name. 

server domai n, lserver domai n C hange the default server to domai n. lserver uses the initial server to look up informa¬ 
tion about d oma i n , whereas server uses the current default server. If an authoritative 
answer can't be found, the names of servers that might have the answer are returned, 
root C hanges the default server to the server for the root of the domain name space. 

Currently, the host ns.intemic.net is used. (This command is a synonym for lserver 
ns.intemic.net.) The name of the root server can be changed with the set root 
command. 

finger [ n a me ] [ > f i i ename ], Connects with the finger server on the current host. The current host is defined when 

finger [name ][» f i i ename ] a previous lookup for a host was successful and returned address information (seethe 

set query-type= a command), name isoptional. > and »can be used to redirect output 
in the usual manner. 

is [option] domain [> filename], List the information availablefor domain, optionally creating or appending to 
is [option] domain [» filename] f i i ename . T he default output contains hostnames and their Internet addresses, opt i on 

can be one of thefollowi ng: 


finger [name ] [> f i I ename ], 
finger [name ][» f i I ename ] 


Is [option] domain [> filename], 
Is [option] domain [» filename] 


quer yt ype 


Lists all records of the specified type (see 
querytype). 

Lists aliases of hosts in the domain. Synonym for 


Lists all records for the domain. Synonym for 


class=vaI ue 


-h ListsCPU and operating system information for 

the domain. Synonym for -t hinfo. 

-s Listswell-known servicesof hosts in thedomain. 

Synonym for -t wks. W hen output is directed to a 
file, hash marks are printed for every 50 records 
received from the server. 

view filename Sorts and lists the output of previous is commands 

with more(l). 

help, ? Printsabrief summary of commands, 

exit Exits the program. 

set keyword [=vai ue] T hiscommand is used to change state information 

that affects the lookups. Valid keywords are 
an P ri nts th e cu rrent val ues of th e f requen tl y u sed 

optionsto set. Information about the current 
default server and host is also printed. 

Change the query class to one of the following: 
in The I nternet class. 

chaos The Chaos class. 
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[no]debug 
[no]d2 

domain=name 


srchlist=namel /name2 /... 


[no]defname 

[no]search 

port=val ue 

querytype=val ue, type=val ue 


[no]recurse 
retry=n umber 


hesiod T he M IT Athena H esiod class. 

any Wildcard (any of the above). 

T he class specifiesthe protocol group of the information. (Default = in, abbreviation = 
cl.) 

T urn debugging modeon. A lot more information isprinted about the packet sentto 
the server and the resulting answer. (D efault = nodebug, abbreviation = [no]deb.) 

T urn exhaustive debugging mode on. Essentially, all fieldsof every packet are printed. 

(D efault = nod 2 .) 

Change the default domain name to name. The default domain name is appended to a 
lookup request depending on the state of the def name and search options. The domain 
search list contains the parents of the default domain if it has at least two components in 
its name. For example if the default domain iscc.Berkeiey.EDu, thesearch list is 
cc.Berkeiey.EDu and Berkeiey.EDu. U se the set srchiist command to specify a different 
list. Use the set all command to display the list. (Default = value from hostname, 
/etc/resoiv.conf, or localdo-main, abbreviation =do.) 

Change the default domain nametonamei andthedomain search list tonamei, name 2 , 
and so on. A maximum of six names separated by slashes!/) can be specified. For 
example, set srchlist=lcs.MIT.EDU/ai.MIT.EDU/MIT.EDU SetSthedomain to lcs.MIT.EDU 
and thesearch list to the three names. This command overrides the default domain 
name and search list of the set domain command. Use the set an command to display 
the list. (D efault = value based on hostname /etc/resoiv.conf, or local-domain, 
abbreviation = srchi.) 

If set, append the default domain name to a singlecomponent lookup request (that is, 
onethat does not contain aperiod). (Default =defname, abbreviation =[no]def.) 

If the lookup request contains at least one period but doesn't end with a trailing period, 
append the domain names in the domain search list to the request until an answer is 
received. (Default = search, abbreviation = [ no]sea.) 

C hange the default TCP/U D P nameserver port to value. (Default = 53 , abbreviation = 
po.) 

Change thetype of information query to one of thefollowing: 

a The host's Internet address. 

cname The canonical name for an alias. 

hinfo The host CPU and operating system type. 

minfo Themailboxormail list information. 

mx The mail exchanger. 

ns The nameserver for the named zone 

ptr The host name if the query is an I nternet address; otherwise the pointer 

to other information. 

soa The domain's" start- of-auth ori ty" information. 

txt The text information. 

uinfo Theuser information. 

wks The supported well-known services. 

Other types (any, axfr, mb, md, mf, null) are described in the RFC-1035 document. 

(D efault = a, abbreviations = q, ty.) 

T ell the nameserver to query other servers if it does not have the information. (D efault = 
recurse, abbreviation = [ no]rec.) 

Set the number of retries to number . When a reply to a request is not received within a 
certain amount of time (changed with set timeout), the timeout period is doubled and 
the request is resent. The retry value controls how many times a request is resent before 
giving up. (Default = 4 , abbreviation =ret.) 



overchan 



root=host 


timeout=number 
[no]vc 

[no]ignoretc 


Change the name of the root server to host . This affects the root command. (Default = 
ns.internic.net, abbreviation =ro.) 

Change the initial timeout interval for waiting for a reply to n u mbe r seconds. Each retry 
doubles the timeout period. (Default =5 seconds, abbreviation =ti.) 

Always use a virtual circuit when sending requests to the server. (Default =novc, 
abbreviation =[no]v.) 

Ignore packet truncation errors (Default =noignoretc, abbreviation = [ no] ig.) 


DIAGNOSTICS 


If the lookup request was not successful, an error message is printed. Possible errors are 


Timed out 

No response from server 
No records 


Non-existent domain 
Connection refused, 
Network is unreachable 
Server failure 

Refused 
Format error 


The server did not respond to a request after a certain amount of time (changed with 
set ttmeout=v ai ue ) and a certain number of retries (changed with set retry=vai ue). 

N 0 nameserver isrunningon theserver machine. 

The server does not have resource records of the current query type for the host, 
although the hostname is valid. The query type is specified with the set querytype 
command. 

The host or domain namedoesnot exist. 

The connection to the name or finger server could not be made at the current time. 
This error commonly occurs with is and finger requests. 

The nameserver found an internal inconsistency in its database and could not return a 
valid answer. 

The nameserver refused to service the request. 

The nameserver found that the request packet was not in the proper format. It may 
indicate an error in nsiookup. 


FILES 

/Etc/Resolv.Conf 
$H0ME/.nslookuprc 
/usr/share/misc/nslookup. help 


Initial domain name and nameserver addresses. 
User's initial options. 

Summary of commands. 


ENVIRONMENT 

hostaliases File containing host aliases. 

localdomain 0 verrides default domain. 


SEE ALSO 

resoiver(3), resoiver(5), named(8), RFC 1034 "Domain Names - Concepts and Facilities," RFC 1035 "Domain Names - 
Implementation and Specification” 

AUTHOR 

Andrew Cherenson 

24Junel990 


overchan 

overchan— U pdate the news overview database. 
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SYNOPSIS 

overchan [ -D dir ][-c ] [f i I e... ] 

DESCRIPTION 

overchan reads article data from files or standard input if none are specified. (A single dash in the file list means to read 
standard input.) It uses this information to update the news overview database, overchan is designed to be used by 
InterN etN ews or the C N ewsmkov packages to update the database as the articles come in. T he database for each newsgroup 
is stored in afilenamed .overview in anewsgroup directory within the overview database tree. 

overchan locks the database file (by locking an auxiliary file) before appending the new data. T o purge data after articles have 
been expired, seeexpireover(8). 

By default, overchan processes its input as an inn overview stream written as a wo entry in thenewsfeeds(5) file: 
overview: *:Tc,WO: /news/bin/overchan 

This data consists of a line of text separated into two parts by a tab. The first part is a list of all relative pathnames where the 
article has been written with a single space between entries. The second part is the data to be written into the overview file, 
except that the initial article number is omitted. 

T o process the output of the mkov(8) program, usethe-c flag. This format is descri bed in thenov distribution. 

The-D flag can be used to specify where the databases are stored. The default directory is /news/spool. 

HISTORY 

W ritten by Rob Robertson (rob@vioiet.benkeiey.edu) and Rich $alz (rsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

newsfeeds(5), newsoverview(5), newsoverview(8) 

pac 

pac— Printer/pi otter accounting information. 

SYNOPSIS 

pac [-P printer] [ - c ] [-m] [-p price] [ - s ] [ - r ] [name ...] 

DESCRIPTION 

pac reads the printer/plotter accounting files, accumulating the number of pages (the usual case) or feet (for raster devices) of 
paper consumed by each user and printing how much each user consumed in pages or feet and dollars. 

Options and operands available 

-p pri nter Accounting is done for the named printer. Usually, accounting is done for the default 

printer (site dependent), or the value of the environment variable printer is used. 

-c Flag causes the output to besorted by cost; usually, the output is sorted alphabetically 

by name. 

-m Flag causes the hostname to be ignored in the accounting file. This allows for a user on 

multiple machines to have all his printing charges grouped together. 

-p price The value price is used for the cost in dollars instead of the default value of 0.02 or the 

price specified in /etc/printcap. 

-r Reverse the sorting order. 

-s Accounting information is summarized on the summary accounting file; this summari¬ 

zation is necessary because on a busy system, the accounting file can grow by several 
lines per day. 




pcnfsd 



names 


Statistics are only printed for users named; usually, statistics are printed for every user 
who has used any paper. 


FILES 


/var/account/?acct 
/var/account/?_sum 
/etc/printcap 

SEE ALSO 

printcap(5) 


Raw accounting files 
Summary accounting files 
P ri nter capabi I i ty database 


BUGS 

The relationship between the computed price and reality is as yet unknown. 


HISTORY 

Thepac command appeared in BSD 4.0. 


BSD 4.2,16 March 1991 


pcnfsd 

pcnfsd— (PC )N FS authentication and print request server 

SYNOPSIS 

/usr/etc/rpc.pcnfsd 

AVAILABILITY 

Thisprogram isfreely redistributable. 

DESCRIPTION 

pcnfsd is an RPC server that supports ON C clients on PC (DOS, OS/2, M acintosh, and other) systems. This page describes 
version 2 of the pcnfsd server. 

rpc.pcnfsd may be started from /etc/rc.local or by the inetd(8) superdaemon. It reads the configuration file 
/etc/pcnfsd.conf if present and then services RPC requests directed to program number 150001 . This release of the pcnfsd 
daemon supports both version 1 and version 2 of the pcnfsd protocol. Consult the rpcgen source file pcnfsd. x for details of 
the protocols. 

The requests serviced by pcnfsd fall into three categories: authentication, printing, and other. Only the authentication and 
pri nti n g servi ces h ave ad m i n i strati ve si gn i f i can ce. 

AUTHENTICATION 

When pcnfsd receives a pcnfsd auth or pcnfsd 2 auth request, it "logs in" the user by validating the username and password 
and returning the corresponding U ID, GIDs, home directory, and umask. If pcnfsd was built with thevmp compile-time 
option, it also appends a record to thewtmp(5) database. If you do not want to record PC logins in this way, you should add a 
lineof theform 
wtmp off 

to the /etc/pcnfsd.conf file. 

Bydefault, pcnfsd only allows authentication or print requests for users with U ID sin the range 101 to 60002 . (This 
corresponds in svr4 to the range for non-system accounts.) T 0 override this, you may add a line of theform 
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uidrange r ange [ ,r ange ]... 

to the /etc/pcnfsd.conf file. H ere, each range is of the form u i d or ui d -ui d , indicating an inclusive range. 

PRINTING 

pcnf sd supports a printing model based on the use of N FS to transfer the actual print data from the client to the server. T he 
client system issues a pcnfsd_pr_init or pcn-fsd 2 _pr_init request, and the server returns the path to a spool directory that the 
client may use and which is exported by N FS. pcntsd creates a subdirectory for each of its clients: The parent directory is 
usually /usr/spooi/pcnts and the subdirectory is the hostname of the client system. If you want to use a different parent 
directory, you should add a line of the form 

spooldir path 

to the /etc/pcnfsd.conf file. 

Once a client has mounted the spool directory using N FS and has transferred print data to a file in this directory, it issues a 
pcnfsd_pr_start or pcnfsd 2 _pr_start request, pcnfsd handles this, and most other print-related requests, by constructing a 
command based on the printing services of the server operating system and executing the command using the identity of the 
PC user. Because this involves set-user-ID privileges, pcnfsd must be run as root. 

Every print request from the client includes the name of the printer that is to be used. In Linux, this name corresponds to a 
printer definition in the/etc/printcap(5) database. If you want to define a non-standard way of processing print data, you 
should define a new printer and arrange for the client to print to this printer. There are two ways of setting up a new printer. 
The first involves the addition of an entry to /etc/printcap(5) and the creation of filters to perform the required processing. 
This is outside the scope of this discussion. In addition, pcnfsd includes a mechanism by which you can define virtual 
printers known only to pcnfsd clients. Each printer is defined by a line in the /etc/pcnfsd.conf file of the foil owing form: 
printer name alias-for command 

name is the name of the printer you want to define, ai i as- for isthenameof a "real" printer that corresponds to this printer. 
For example, a request to display the queue for name is translated into the corresponding request for the printer a i i as-for . If 
you have defined a printer in such away that there is no "real" printer to which it corresponds, use a single - for this field. 
(See the definition of the printer test for an example.) command is a command that will be executed whenever a file is printed 
on name. This command is executed by the shell at / bin/sh using the -c option. For complex operations, you should 
construct an executable shell program and invokethat in command. 

Consider the following sample /etc/pcnfsd.conf file: 

printer rotated lw /usr/local/bin/enscript -2r $FILE 
printer test - /usr/bin/cp $FILE/usr/tmp/$HOST$USER 

If a client system prints a job on the printer rotated, the utility enscript is invoked to pre-process the file sfile. In this case, 
the - 2 r option causes the file to be printed in two-column rotated format on the default PostScript printer. If the client 
requests a list of the print queue for the printer rotated, the pcnfsd daemon translates this into a request for a listing for the 
printer iw. 

The printer test is used only for testing. Any file sent to this printer iscopied into /usr/tmp. Any request to list the queue, 
check the status, and so on of printer test is rejected because the a i i as-for is specified as -. 



plipconfig 



RECONFIGURATION 

pcnfsd detects when printers are added or deleted and rebuilds its list of valid printers. To do this, it checks the modification 
time of /etc/printcap. H owever, it doesnot monitor the file /etc/pcnfsd. cont for updates; if you change thisfile, it is still 
necessary to kill and restart pcnfsd so the changes can take effect. 

FILE 

/etc/pcnfsd.conf 

SEE ALSO 

lpr(l), lprm(l), lpc(8), lpq(l) 

25Junel995 


plipconfig 

plipconfig— Fine-tune PLIP device parameters. 

SYNOPSIS 

plipconfig i nt erf ace 

plipconfig interface [nibble NN] [trigger NN] [unit NN] 

DESCRIPTION 

plipconfig is used to improvePLIP performance by changing the default timing parameters used bythePLIP protocol. 
Results are dependent on the parallel port hardware, cable, and theCPU speed of each machine on each end of thePLIP 
link. 

If the single i nterface argument isgiven, plipconfig displays the status of the given interface only. Otherwise, ittriesto set 
the options 

OPTIONS 

nibble nn Sets the nibble wait value in microseconds. D efault is 3000 . 

trigger nn Sets the trigger wait value in microseconds. D efault is 500 . 

unit nn Sets the number of units of delay. D efault is 1 . 

In some cases, PLIP speed can be improved by lowering the default values. Values that are too low might cause excess use of 
CPU, poor interrupt response time resulting in serial ports dropping characters, or in dropping PLIP packets. Changing the 
plip MTU can also affect PLIP speed. 

SEE ALSO 

ifconfig(8) 

BUGS 

N one so far. 

AUTHOR 

J ohn Paul M orrison (jmorriso@bogomips.ee.ubc. ca, ve7jpm@ve7jpm.ampr.org) 


1 July 1994 
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ping 

ping— Send ICMP echo_request packets to network hosts. 

SYNOPSIS 

/etc/ping [ -r ][-v ] host [ packetsize ][count ] 

DESCRIPTION 

TheD ARPA Internet is a large and complex aggregation of network hardware, connected together by gateways. T racking a 
single-point hardwareor software failure can often bedifficult. Ping utilizesthe IC M P protocol's mandatory echo_request 
datagram to elicit an ICMP echo_response from a host or gateway. echo_request datagrams ("pings") have an IP and 1C M P 
header, followed by a struct timevai and then an arbitrary number of "pad” bytes used to fill out the packet. D efault 
datagram length is 64 bytes, but this may be changed using the command-line option. Other options are 

-r Bypass the normal routing tables and send directly to a host on an attached network. If 

the host is not on a directly attached network, an error is returned. Thisoption can be 
used to ping a local host through an interface that has no route through it (for example, 
after the interface was dropped by routed(8C)). 

-v V erbose output. ICMP packets other than echo_response that are received are listed. 

When using ping for fault isolation, it should first be run on the local host to verify that the local network interface is up and 
running. Then, hosts and gateways further away should be pinged. Ping sends one datagram per second and prints one line 
of output for every echo_response returned. N o output is produced if there is no response. If an optional count is given, only 
that number of requests is sent. Round-trip times and packet-loss statistics are computed. W hen all responses have been 
received or the program times out (with a count specified), or if the program is terminated with asiGiNT, a brief summary is 
displayed. 

Thisprogram is intended forusein network testing, measurement, and management. 11 should beused primarily for manual 
fault isolation. Because of the load it could impose on the network, it is unwise to use ping during normal operations or from 
automated scripts. 

AUTHOR 

M ikeM uuss 

SEE ALSO 

netstat(l), ifconfig(8) 

19 September 1988 


portmap 

portmap— D ARPA port to RPC program number mapper. 

SYNOPSIS 

portmap [-d] 

DESCRIPTION 

portmap isa server that converts RPC program numbersinto DARPA protocol portnumbers. It must be running in order to 
make RPC calls. 

When an RPC server isstarted, it tel Is portmap what port number it is listening to and what RPC program numbers it is 
prepared to serve. W hen a client wants to make an RPC call to a given program number, it first contacts portmap on the 
server machineto determine the port number where RPC packets should be sent. 



powerd 


1359 


portmapmust be started before anyRPC servers are invoked. 

Usually, portmap forks and dissociates itself from the terminal like any other daemon. Portmap then logs errors using 
syslog(3). 

Option available 

-d (debug) prevents portmap from running as a daemon and causes errors and debugging information to be printed to the 
standard error output. 

SEE ALSO 

inetd.conf(5), rpcinfo(8), inetd(8) 

BUGS 

If portmap crashes, all servers must be restarted. 

HISTORY 

The portmap command appeared in BSD 4.3. 

BSD 4.3,16 March 1991 


powerd 

powerd— M onitor a serial line connected to a U PS. 

SYNOPSIS 

/etc/powerd seri al■devi ce 

DESCRIPTION 

powerd isadaemon process that sits in thebackground and monitorsthe state of theDCD line of the serial device. It is 
meant that this line is connected to a U PS (Uninterruptible Power Supply) so that it knows about the state of the U PS. As 
soon as powerd senses that the power is failing (it sees that DCD goes low) it notifies init(8) and init executes the powerwait 
and powertaii entries. If powerd senses that the power has been restored, it notifies init again and init executes the 
powerokwait entries. 

ARGUMENTS 

serial - device Some serial port that isnot being used by some other device and does not 

share an interrupt with any other serial port. 


DIAGNOSTICS 

powerd regularly checks the D SR lineto see if it's high. DSR should be directly connected to DTR and powerd keeps that line 
high, so if DSR is low, something is wrong with the connection, powerd notifies you about this fact every two minutes. W hen 
it sees that the connection is restored, itwill say so. 

IMPLEMENTATION 

It's pretty simple to connect your U PS to the Linux machine. T he steps are easy: 

1. M ake sure you have an U PS with asimplerelaisoutput: it should close its connections (make) if the power is gone, and 
it should open its connections (break) if the power is good. 

2. Buy a serial plug. Connect the DTR lineto the DSR line directly. Connect the DTR line and theDCD line with a 10 
kilo ohm resistor. Connect the relais-output of theU PS to GROU N D and theDCD line. If you don't know what pins 
DSR, DTR, DCD and GROU N D are, you can always ask at the store where you bought the plug. 

3. You'reall set. 
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BUGS 

Well, it's not a real bug but powerd should be able to do a broadcast or something on the Ethernet in case more Li nux-boxes 
are connected to the same U PS and only one of them is connected to the U PS status line. 

SEE ALSO 

shutdown(8), init(8), inittab(5) 

AUTHOR 

M iguel van Smoorenburg (miquels@drinkel.nl.mugnet.org) 

14 Februaryl994 


PPPd 

pppd— Point-to-Point Protocol daemon. 

SYNOPSIS 

pppd [ 11 y _ n a me ] [speed ] [o p t i o n s ] 


DESCRIPTION 

The Point-to-Point Protocol (PPP) provides a method for transmitting datagrams over serial point-to-point links. PPP is 
composed ofthree parts a method for encapsulating datagrams over serial links an extensible Link Control Protocol (LCP), 
and a family of Network Control Protocols (N CP) for establishing and configuring different network-layer protocols 

The encapsulation scheme isprovided by driver code in the kernel, pppd provides the basic LCP, authentication support, and 
an NCP for establishing and configuring the Internet Protocol (IP) (called the IP Control Protocol, IPCP). 


FREQUENTLY USED OPTIONS 

11 y _ n a me 


speed 


asyncmap map 


auth 

connect p 

crtscts 

defaultroute 


Communicate over the named device. The string /dev/ is prepended if necessary. If no 
device name is given, or if the name of the controlling terminal is given, pppd uses the 
controlling terminal and does not fork to put itself in the background. 

Set the baud rate to speed (a decimal number). On systems such as4.4BSD and 
N etBSD, any speed can be specified. Other systems (such as SunOS) allow only a 
limited set of speeds. 

Set the async character rnaptomap.Thisrnap describes which control characters cannot 
be successfully received over the serial line, pppd asks the peer to send these characters as 
a 2-byte escape sequence. The argument is a 32-bit hex number with each bit represent¬ 
ing a character to escape. BitO ( 00000001 ) represents the character 0 x 00 ; bit 31 ( 80000000 ) 
represents the character 0 xi t or \ If multiple asyncmap optionsare given, the values are 
oRed together. If no asyncmap option isgiven, no async character map is negotiated for 
the receive direction; the peer should then escape all control characters. 

Require the peer to authenticate itself before allowing network packets to be sent or 
received. 

Use the executable or shell command specified by p to set up theserial li ne. This script 
typically uses the chat(8) program to dial the modem and start the remote PPP session. 
Use hardware flow control (that is RTS/CTS) to control the flow of data on theserial 
port. If neither the crtscts nor the -crtscts option isgiven, the hardware flow control 
setting for theserial port is left unchanged. 

Adda default route to the system routi ng tables, usi ng the peer as the gateway, when 
IPCP negotiation is successfully completed. This entry is removed when thePPP 
connection is broken. 



disconnect p 

escape xx ,yy,... 

file f 
lock 

mru n 

mtu n 

netmask n 

passive 

silent 

OPTIONS 

local IP address :remote 


-ac 

-all 

-an 

-as n 


pppd 



Run the executable or shell command specified by p after pppd has terminated the link. 
This script could, for example, issue commands to the modem to cause it to hangup if 
hardwaremodem control signals were not available. 

Specifies that certain characters should be escaped on transmission (regardlessof whether 
the peer requests them to be escaped with its async control character map). The 
characters to be escaped are specified as a list of hex numbers separated by commas. 

N otethat almost any character can be specified for the escape option, unlike the 
asyncmap option, which only allows control characters to be specified. The characters 
that cannot be escaped are those with hex values 0 x 20 - 0x3f oroxse. 

Read optionsfrom filef (the format is described later). 

Specifies that pppd should create a U U C P-style lock fi le for the serial device to ensure 
exclusive access to thedevice. 

Set the M RU (M aximum Receive U nit) value to n for negotiation, pppd asks the peer to 
send packets of no more than n bytes. The minimum M RU value is 128 . The default 
M RU value is 1500 . A value of 296 is recommended for slow I inks (40 bytes for TCP/IP 
header plus 256 bytes of data). 

Set theMTU (M aximum T ransmit Unit) value to n. U nless the peer requests a smaller 
value viaM RU negotiation, pppd requests that the kernel networking code send data 
packets of no more than n bytes through thePPP network interface. 

Set the interface netmask to n, a 32-bit netmask in decimal dot notation (such as 
255 . 255 . 255 . 0 ). If thisoption isgiven, the value specified isoRed with thedefault 
netmask. The default netmask ischosen based on the negotiated remotelP address; it is 
the appropriate network mask for the class of the remote IP address oRed with the 
netmasksfor any non-point-to-point network interfaces in the system that are on the 
same network. 

Enables thepassive option in theLCP. With thisoption, pppd attempts to initiatea 
connection; if no reply is received from the peer, pppd then waits passively for a valid 
LC P packet from the peer (i nstead of exiting as it does without this option). 

With thisoption, pppd does not transmit LCP packets to initiate a connection until a 
valid LCP packet is received from the peer (as for the passive option with ancient 
versions of pppd). 


ip address Set the local and/or remote interface IP addresses. Either one may be 

omitted. The IP addresses can be specified with a host name or in decimal 
dot notation (such as 150 . 234 . 56 . 78 ). T hedefault local address isthe 
(first) IP address of the system (unless the noipdefauit option isgiven). 
The remote address is obtained from the peer if not specified in any 
option. Thus, in simplecases, thisoption isnot required. If a local and/or 
remotelP address isspecified with thisoption, pppd does not accept a 
different value from the peer in the I PC P negotiation, unless the 
ipcp-accept-iocai and/or ipcp-accept-remote options are given. 

D isableAddress/Control compression negotiation (usedefault, address 
control field compression disabled). 

Don't request or allow negotiation of any optionsfor LCP and IPCP (use 
default values). 

D isable asyncmap negotiation (use the default asyncmap; that is, escape all 
control characters). 

Same as asyncmap n. 
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bsdcomp nr ,nt 


-bsdcomp 

+chap 

■chap 

chap-interval n 
chap-max-challenge n 

chap-restart n 

■crtscts 


-d 

debug 


-defaultroute 

-detach 

dns-addr n 

domain d 


-ip 


+ip-protocol 

-ip-protocol 

+ipx-protocol 


Request that the peer compress packets that it sends, usi ng the 
BSD-Compress scheme, with a maximum code size of nr bits and agree to 
compress packets sent to the peer with a maximum code size of nt bits. If 
nt is not specified, it defaults to the value given for nr . Values in the range 
9 to 15 may be used for nr and nt ; larger values give better compression 
but consume more kernel memory for compression dictionaries. 
Alternatively, a value of a for nr or nt disables compression in the 
corresponding direction. 

D isables compression; pppd does not request or agree to compress packets 
usi ng the BSD-C ompress scheme. 

Require the peer to authenticate itself usi ng C H AP (C ryptographic 
H andshakeAuthentication Protocol) authentication. 

D on't agree to authenticate using C H AP. 

If this option is given, pppd rechallenges the peer every n seconds. 

Set the maximum number of CHAP challenge transmissions to u (default 
is 10 ). 

Set theC H AP restart i nterval (retransmission timeout for challenges) to n 
seconds (default is3). 

D i sable hardware flow control (RTS/CTS) on the serial port. If neither 
the crtscts nor the -crtscts option is given, the hardware flow control 
setting for theserial port is left unchanged. 

Increase debugging level (same as the debug option). 

Increase debugging level (sameas -d). If thisoption isgiven, pppd logs the 
contentsof all control packets sent or received in a readable form. The 
packets are logged through sysiog with facility daemon and level debug. 
This information can be directed to a file by setting up /etc/sysiog. cont 
appropriately (see sysiog.cont (5)). 

D isable the defaultroute option. The system administrator who wants to 
prevent users from creating default routes with pppd can do so by placing 
thisoption in the /etc/ppp/options file 

Don't fork to becomea background process (otherwise, pppd will do so if 
aserial device other than its controlling terminal is specified). 

Thisoption sets the IP address or addresses for the D omain N ame Server. 
It is used by M icrosoft Windows clients. The primary DNS address is 
specified by the first instance of the dns-addr option. The secondary is 
specified by the second instance. 

Append the domain named tothelocal hostnamefor authentication 
purposes. For example if gethost-named returns the name porsche, but 
thefully qualified domain nameisporsche.Quotron.coM, you use the 
domain option to set the domain name to Quotron.coM. 

DisablelP address negotiation. If thisoption isused, theremotelP 
address must be specified with an option on the command line or in an 
optionsfile. 

E nablethe I PC P and IP protocols. This is the default condition. This 
option is only needed if the default setting is - ip-protocol. 

D isable the I PC P and IP protocols. This should only be used if you know 
you are using a client that only understands IPX and you don't want to 
confusetheclientwith theIPCP protocol. 

EnablethelPXCP and IPX protocols. T his is the default condition if 
your kernel supportsIPX. This option isonly needed if the default setting 
is -ipx-protocoi. If your kernel does not support IPX, thisoption has no 
effect. 



-ipx-protocol 

ipcp-accept-local 
ipcp-accept-remote 
ipcp-max-configure n 
ipcp-max-failure n 
ipcp-max-terminate n 
ipcp-restart n 
ipparam st ri ng 

ipx-network n 


ipx-node n:m 


ipx-router-name string 
ipx-routing n 

ipxcp-accept-local 

ipxcp- accept - network 

ipxcp-accept -remote 

ipxcp-max-configure n 


Disablethe IPXCP and IPX protocols. This should only beused ifyou 
know you are using a client that only understands IP and you don't want 
to confuse the client with thelPXCP protocol. 

With this option, pppd accepts the peer's idea of a local IP address, even if 
thelocal IP address was specified in an option. 

With this option, pppd accepts the peer's idea of its (remote) IP address, 
even if the remote IP address was specified in an option. 

Set the maximum number of IPC P configure-request transmissionsto n 
(default is 10). 

Set the maximum number of IPCP configure-N AKsreturned before 
starting to send configure-Rqects instead to n (default is 10). 

Set the maximum number of IPCP terminate-request transmissionsto n 
(default is 3 ). 

Set the IPCP restart interval (retransmission timeout) ton seconds 
(default is 3 ). 

Provides an extra parameter to the ip-up and ip-down scripts. If this 
option is given, the s t r i ng supplied is given as the sixth parameter to 
those scripts. 

Set the IPX network number in thelPXCP configure request frame to n. 
There is no valid default. If thisoption is not specified, the network 
number is obtained from the peer. If the peer does not have the network 
number, thelPX protocol is not started. This is a hexadecimal number 
and isentered without any leading sequence such as@x. It isrelated to the 
ipxcp-accept-network option. 

Set the IPX node numbers. The two node numbers are separated from 
each other with acolon character. The first numbern isthe local node 
number. The second number m isthe peer's node number. Each node 
number is a hexadecimal number to themaximum often significant 
digits. The node numbers on theipx-network must be unique. There is 
no valid default. If thisoption is not specified, the node number is 
obtained from the peer. Thisoption isa related to the ipxcp-accept-iocai 
and ipxcp-accept-remote Options. 

Set the name of the router. T his isa string and is sent to the peer as 
information data. 

Set the routing protocol to be received by thisoption. M ore than one 
instance of ipx-routing may be specified. The none option ( 0 ) maybe 
specified astheonly instance of ipx-routing. The values are@ for none, 2 
for RIP/SAP, and 4 for NLSP. 

Accept the peer's NAK for the node number specified in theipx-node 
option. If a node number was specified and it is nonzero, the default is to 
insist that the value be used. Ifyou include thisoption, you permitthe 
peer to override the entry of the node number. 

Accept the peer's NAK for the network number specified in theipx- 
network option. If a network number was specified and it is nonzero, the 
default isto insist that the value be used. Ifyou includethisoption, you 
permit the peer to override the entry of the node number. 

U se the peer's network number specified in the configure request frame. 

If a node number was specified for the peer and thisoption was not 
specified, the peer isforced to use the value that you specified. 

Set the maximum number of IPXC P configure request frames that the 
system sends to n. The default is 10. 
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ipxcp-nax-failure n 
ipxcp-max-terminate n 

kdebug n 


lcp-echo-failure n 


lcp-echo-interval n 


lcp-max-configure n 
lcp-max-failure n 
lcp-max-terminate n 
lcp-restart n 

local 

login 

modem 


-mn 

-mru 

name n 
noipdefault 


Set the maximum number of IPXCP NAK frames that the local system 
sends before it rqects the options. T he default value is3. 

Set the maximum number of IPXC P terminate request frames before the 
local system considers that the peer is not listening to them. The default 
value is 3 . 

Enable debugging code in the kernel-level PPP driver. Theargumentn is 
a number that isthesum of the followi ng values: i to enable general 
debug messages, 2 to request that the contents of received packets be 
printed, and 4 to request that the contents of transmitted packets be 
printed. 

If thisoption is given, pppd presumes the peer is dead if n LCP echo- 
requests are sent without receiving a valid LCP echo-reply. If this 
happens, pppd terminates the connection. Use of thisoption requiresa 
nonzero value for theicp-echo-intervai parameter. Thisoption can be 
used to enable pppd to terminate after the physical connection has been 
broken (for example the modem has hung up) in situations where no 
hardware modem control lines are available 
Ifthisoption is given, pppdsendsan LCP echo-request frame to the peer 
every n seconds. Under Linux, the echo-request is sent when no packets 
are received from the peer for n seconds. Usually, the peer should respond 
to theecho-request by sending an echo-reply. Thisoption can be used 
with the icp-echo-faiiure option to detect that the peer is no longer 
connected. 

Set the maximum number of LC P configure-request transmissions to n 
(default is 10 ). 

Set the maximum number of LCP configure-N AKs returned before 
starting to send configure-Rqects instead to n (default is 10). 

Set the maximum number of LC P terminate-request transmissionsto n 
(default is 3). 

Set the LC P restart interval (retransmission timeout) to n seconds (default 
is 3). 

Don't use the modem control lines. W ith thisoption, pppd ignores the 
state of the CD (Carrier Detect) signal from the modem and does not 
change the state of the DTR (D ata T erminal Ready) signal. 

Use the system password database for authenticating the peer using PAP, 
and record the user in the system wtmp file. 

Use the modem control lines. Thisoption is the default. With this 
option, pppd waits for the CD (Carrier Detect) signal from the modem to 
be asserted when opening the serial device (unless a connect script is 
specified), and it dropstheDTR (DataTerminal Ready) signal briefly 
when theconnection isterminated and before executing the connect 
script. On Ultrix, thisoption implies hardware flow control, as for the 
crtscts option. 

D isable magic number negotiation. W ith thisoption, pppd cannot detect 
alooped-backline. 

D isable MRU (M axi mum Receive Unit) negotiation. With thisoption, 
pppd uses the default M RU value of 1500 bytes. 

Set the name of the local system for authentication purposes to n. 

Disables the default behavior when no local IP address is specified, which 
isto determine (if possible) the local IP address from the hostname With 
thisoption, the peer must supply the local IP address during I PC P 



-p 

+pap 

-pap 

papcrypt 

pap-max-authreq n 
pap-restart n 
pap-timeout n 
-pc 

persist 

predlcomp 

-predlcomp 

proxyarp 

-proxyarp 

remotename n 

+ua p 


usehostname 

user u 

-vj 

-vjccomp 

vj-max-slots n 


negotiation (unless it specified explicitly on the command line or in an 
optionsfile). 

Same as the passive option. 

Require the peer to authenticate itself using PAP. 

Don't agree to authenticate using PAP. 

Indicates that all secrets in the /etc/ppp/pap-secrets file, which are used 
for checking the identity of the peer, are encrypted, and thuspppd should 
not accept a password (before encryption) that is identical to the secret 
from the /etc/ppp/pap-secrets file. 

Set the maximum number of PAP authenticate-request transmissions to n 
(default is 10). 

Set the PAP restart interval (retransmission timeout) to n seconds (default 
is 3 ). 

Set the maximum time that pppd waits for the peer to authenticate itself 
with PAP to n seconds (0 means no limit). 

D isable protocol field compression negotiation (use default, protocol field 
compression disabled). 

D 0 not exit after a connection isterminated; instead, try to reopen the 
connection. 

Attempt to request that the peer send the local system frames, which have 
been compressed by the Predictor -1 compression. The compression 
protocolsmust beloaded orthisoption isignored. 

Do not accept Predictor -1 compression, a/en if the peer wants to send 
this type of compression and support has been defined in the kernel. 

Add an entry to thissystem'sARP (Address Resolution Protocol) table 
with the IP address of the peer and the Ethernet address of this system. 

D isable the proxyarp option. The system administrator who wants to 
prevent users from creating proxy ARP entries with pppd can do so by 
placing this option in the /etc/ppp/options fi le. 

Set the assumed name of the remote system for authentication purposes 
to n. 

Agree to authenticate using PAP (Password Authentication Protocol) if 
requested by the peer and use the data in file p for the user and password 
to send to the peer. The file contains the remote username, followed by a 
newline followed by the remote password, followed by anewline. This 
option is obsolescent. 

Enforcetheuseof thehostnameasthenameof thelocal system for 
authentication purposes (overrides the name option). 

Set the username to use for authenticating this machi ne with the peer 
using PAP to u. 

D isable negotiation of Van J acobson-styleTC P/IP header compression 
(use default, no compression). 

D isable the connection -1 D compression option in Van Jacobson style 
TCP/IP header compression. With this option, pppd does not omit the 
connection -1 D byte from Van Jacobson compressed TCP/IP headers or 
ask the peer to do so. 

Sets the number of connection slots to beused by the Van Jacobson 
TCP/IP header compression and decompression code to n, which must be 
between 2 and 16 (inclusive). 
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xonxoff Use software flow control (XON/XOFF) to control theflowofdataon 

the serial port. This option isonly implemented on Linux systemsat 
present. 

OPTIONS FILES 

Options can betaken from files as well as the command line, pppd reads options from the files /etc/ppp/options and ~/.ppprc 
before looking at the command line. An options file isparsed into a series of words, delimited by whitespace. Whitespace can 
be included in a word by enclosing the word in quotes (■). A backslash (\) quotes the following character. A hash (#) starts a 
comment, which continuesuntil theend of theline. 


AUTHENTICATION 

pppd provides system administrators with sufficient access control so that PPP access to a server machine can be provided to 
legitimate users without fear of compromising the security of the server or the network it's on. In part, this is provided by the 
/etc/ppp/options file, where the administrator can place options to require authentication whenever pppd is run, and in part 
by the PAP and CHAP secrets files, where the administrator can restrict the set of IP addresses that individual users can use. 

The default behavior of pppd isto agree to authenticate if requested and to not require authentication from the peer. 

H owever, pppd does not agree to authenticate itself with a particular protocol if it has no secrets that can be used to do so. 

Authentication is based on secrets, which are selected from secrets fi les ( /etc/ppp/pap- secrets for PAP, 

/etc/ppp/chap-secrets for CHAP). Both secrets files have the same format, and both can store secrets for several combina¬ 
tions of server (authenticating peer) and client (peer being authenticated). N otethat pppd can be both a server and client and 
that different protocols can be used in the two directions if desired. 

A secrets file is parsed into words as for an options file A secret is specified by a line containing at least three words, in the 
order client name, server name and secret. Any following words on the same line are taken to be a list of acceptable IP 
addresses for that client. If there are only three words on theline, it is assumed that any IP address is okay; to disallow all IP 
addresses, use -. If the secret starts with an @, what follows is assumed to be the name of a file from which to read the secret. 

A * as the client or server name matches any name. When selecting a secret, pppd takes the best match—that is, the match 
with thefewest wildcards. 


A secrets file contains both secrets for use in authenticating other hosts and secrets that you use for authenticating yourself to 
others. W hich secret to useischosn based on the names of the host (the local name) and its peer (the remote name). The 
local nameisset as follows: 


If the usehostname option isgiven, 

If the name option is given 

If the local IP address is specified with a 

hostname 


T he local name is the hostname of this machine (with the domain 
appended, if given). 

Use the argument of thefirstname option seen. 

Use that name. Otherwise, use the hostname of this machine (with the 
domain appended, if given). 


When authenticating yourself using PAP, there is also a username, which is the local name by default, but can beset with the 
user option or the+ua option. 

T he remote name is set as follows: 

If the remotename option isgiven Use the argument of the last remote-name option seen. 

If the remote IP address is specified with a Use that host name. Otherwise the remote name isthe null 

hostname string 

Secrets are selected from thePAP secrets file as follows: 

■ For authenticating the peer, look for a secret with client = username specified in thePAP authenti cate-request and 
server = local name. 

■ For authenticating yourself to the peer, look for a secret with client =your username and server = remote name. 



pppd 



When authenticating the peer with PAP, a secret of ■■ matches any password supplied by the peer. If the password doesn't 
match the secret, the password is encrypted using cryptf ) and checked against the secret again; thus secrets for authenticat¬ 
ing the peer can be stored in encrypted form. If the papcrypt option isgiven, thefirst (unencrypted) comparison is omitted 
for better security. 

If thelogin option was specified, the username and password are also checked against the system password database. T hus, 
the system administrator can set up the pap-secrets file to allow PPP access only to certain users and to restrict the set of IP 
addresses that each user can use. Typically, when using thelogin option, the secret in /etc/ppp/pap -secrets is" ■ to avoid the 
need to have the same secret in two places. 

Secrets are selected from theCH AP secrets fileas follows: 

■ For authenticating the peer, look for a secret with client = name specified in theCH AP-Response message and server 
= local name 

■ For authenticating yourself to the peer, look for a secret with client = local name and server = name specified in the 
C FI AP-C hallenge message. 

Authentication must be satisfactorily completed before I PC P (or any other N etwork Control Protocol) can be started. If 
authentication fails, pppd terminates the link (by closing LCP). If IPCP negotiates an unacceptable IP address for the remote 
host, IPCP is closed. IP packets can only be sent or received when IPCP isopen. 

In some cases, it is desi rable to allow some hosts that can't authenticate themselves to connect and useoneof a restricted set 
of IP addresses, a/en when the local host generally requires authentication. If the peer refuses to authenticate itself when 
requested, pppd takes that as equivalent to authenticating with PAP using the empty string for the username and password. 
Thus, by adding a line to the pap-secrets file, which specifies the empty string for the client and password, it is possible to 
allow restricted access to hosts that refuse to authenticate themselves. 

ROUTING 

When IPCP negotiation iscompleted successfully, pppd informsthe kernel of thelocal and remotelP addresses for the PPP 
interface. This is sufficient to create a host route to the remote end of the link, which enables the peers to exchange IP 
packets. Communication with other machines generally requires further modification to routing tables and/or ARP (Address 
Resolution Protocol) tables. In some cases, this is done automatically through the actions of the routed or gated daemons, 
but in most cases, somefurther intervention isrequired. 

Sometimes it is desi rable to add a default route through the remote host, as in the case of a machine whose only connection 
to the Internet is through the PPP interface. The defauitroute option causes pppd to create such a default route when IPCP 
comes up and delete it when the link isterminated. 

In some cases, it is desi rable to use proxy ARP—for example, on a server machine connected to a LAN —to allow other hosts 
to communicate with the remote host. The proxyarp option causes pppd to look for a network interface on the same subnet as 
the remote host (an interface supporting broadcast and ARP, which is up and not a point-to-point or loopback interface). If 
found, pppd creates a permanent, published ARP entry with the IP address of the remote host and the hardware address of 
the network interface found. 

EXAMPLES 

In thesimplest case, you can connect the serial portsof two machines and issueacommand like 

pppd /dev/ttya 9600 passive 

to each machine, assuming there is no getty running on the serial ports. If one machine has a getty running, you can use 
kermit or tip on the other machine to log in to thefirst machine and issue a command like 
pppd passive 

Then exit from the communications program (making sure the connection isn't dropped) and issue a command like 

pppd /dev/ttya 9600 
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The process of logging in to the other machine and starti ng pppd can be automated by using the connect option to run chat: 

pppd /dev/ttya 38400 connect 'chat .login:" "username" 

"Password:" "pass-word" "% " "exec pppd passive"' 

(N ote, however, that running chat like this leaves the password visible in the parameter list of pppd and chat.) 

If your serial connection is any more complicated than a piece of wire, you might need to arrange for some control characters 
to beescaped. In particular, it i s often useful to escapeXON ( / 'Q)andXOFF ('$), using asyncmap aoeae. If the path 
includes a telnet, you probably should escape"] aswell (asyncmap 20030000 ). If thepath includes an riogin, you need to use 
theescape ft option on theend that is running the riogin client becausemany riogin implementationsarenot transparent; 
they remove the sequence (Oxff, Oxff, 0x73, 0x73, followed by any 8 bytes) from the stream. 


DIAGNOSTICS 

M essages are sent to thesysiog daemon using the facility log_daemon. (This can be overridden by recompiling pppd with the 
macro log_ppp defined as the desired facility.) T 0 see the error and debug messages, you need to edit your /etc/sysiog.cont 
file to direct the messages to the desired output device or file. 

The debug option causes the contents of all control packets sent or received to be logged—that is, all LCP, PAP, CHAP, or 
IPCP packets. This can be useful if thePPP negotiation does not succeed. If debugging is enabled at compile time the debug 
option also causes other debugging messages to be logged. 

Debugging can also be enabled or disabled by sending a sigusri to the pppd process. Thissignal acts as a toggle. 

FILES 

/var/run/pppn.pid (BSD or Linux) Process-ID for pppd process on PPP interface unit n. 

/etc/ppp/pppn .pid (Others) 

/etc/ppp/ip-up A program or script that is executed when the link is available for sending and 

receiving IP packets (that is, IPCP has come up). It is executed with the 
param eters i nterface - name tty-device speed local-IP-address remote-1 P-address 
and with its standard input, output and error streams redirected to /dev/nuii. 
This program or script is executed with the same real and effective user-ID as 
pppd— thatis, at I east the effective user-ID and possibly the real user-1 D will be 
root. This is so that it can beused to manipulate routes, run privileged daemons 
(such assend-mail), and so on. Becareful that the contents of the /etc/ppp/ip-up 
and /etc/ppp/ip-down scripts do not compromise your system's security, 
/etc/ppp/ip-down A program or script that is executed when thelink isno longer available for 

sending and receiving IP packets. This script can beused for undoing the effects 
of the /etc/ppp/ip-up script. It is invoked with the same parameters as the ip-up 
script, and the same security considerations apply because it is executed with the 
same effective and real user-1 Ds as pppd. 

/etc/ppp/ipx-up A program or script that is executed when the link is available for sending and 

receiving IPX packets (that is IPXCP hascomeup). It isexecuted with the 
param eters i nterface - name tty-device speed network-number local-IPX-node- 
address remote -1 PX - node - address I ocal - I PX-routi ng-protocol remote-IPX- 
routing-protocol I ocal - I PX- router - name remote -1 PX - router - name ipparam pppd- 
pid and with its standard input, output, and error streams redirected to 
/dev/null. 

Theiocai-IPX-routi ng -protocol and r e mo t e - i PX-routi ng-protocol field may be 
oneof the followi ng: 



pppstats 



/etc/ppp/ipx-down 


/etc/ppp/pap-secrets 
/etc/ppp/chap-secrets 
/etc/ppp/options 

'/.ppprc 

/etc/ppp/options.ttyname 


none to indicate that there is no routing protocol, rip to indicate that RIP/SAP 
should be used, nlsp to indicate that N ovell N LSP should be used, rip nlsp to 
indicate that both RIP/SAP and N LSP should be used. 

This program or script is executed with the same real and effective user-ID as 
pppd — that is, at I east the effective user-ID and possibly the real user-1 D will be 
root. This is so that it can beused to manipulate routes, run privileged daemons 
(such asripd), and so on. Be careful that the contents of the/etc/ppp/ipx-up and 
/etc/ppp/ipx-down scripts do not compromise your system's security. 

A program or script that is executed when thelink isno longer availablefor 
sending and receiving IPX packets. This script can beused for undoing the 
effectsof the /etc/ppp/ipx-up script. Itisinvoked with thesame parameters as 
theipx-up script, and the same security considerations apply because it is 
executed with the same effective and real user-1 Ds as pppd. 

Usernames, passwords, and IP addresses for PAP authentication. 

Names, secrets, and IP addressesforCH AP authentication. 

System default options for pppd, read before user default options or command- 
lineoptions. 

User default options read before command-line options. 

System default options for the serial port being used, read after command-line 
options. 


SEE ALSO 

RFC 1144 

RFC 1321 
RFC 1332 
RFC 1334 
RFC 1548 
RFC 1549 


Jacobson, V. Compressing TCP/IP headers for low-speed serial links February 
1990. 

Rivest, R. TheM D5 M essage-D igest Algorithm. April 1992. 

M cGregor, G. PPP Internet Protocol Control Protocol (IPCP). M ay 1992. 
Lloyd, B.; Simpson, W .A. PPP authentication protocols. 1992 October. 
Simpson, W .A. T hePoint-to-Point Protocol (PPP). D ecember 1993. 
Simpson, W.A. PPP in FI DLC Framing. December 1993. 


NOTES 


SIGINT, SIGTERM 


SIGHUP 


T hefollowing signals have the specified effect when sent to the pppd process: 

T hese si gnals cause pppd to term i nate the Ii nk (by closi ng L C P), restore the seri al 
device settings, and exit. 

Thissignal causes pppd to terminate the link, restore the serial device settings, and 
close the serial device. I f the persist option has been specified, pppd tries to 
reopen the serial device and start another connection. Otherwise, pppd exits 
Thissignal causes pppd to renegotiatecompression.Thiscan beuseful to re¬ 
enable compression after it has been disabled as a result of a fatal decompression 
error. W ith the BSD Compress scheme, fatal decompression errors generally 
indicate a bug in one or another implementation. 


SIGUSR2 


AUTHORS 

D rew Perkins, Brad Clements, Karl Fox, Greg Christy, Brad Parker, and Paul M ackerras (pauius@cs.anu.edu.au) 


pppstats 

pppstats— Print PPP statistics. 
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SYNOPSIS 

pppstats [ -v ][-r ][-c ][-i secs][unit# ] 

DESCRIPTION 

pppstats prints PPP-related statistics. 

The -vflag causes pppstats to display additional statistics, such as the number of packets tossed (that is, which theVJ TCP 
header decompression code rejected). 

The -r flag causes pppstats to display the overall packet compression rate. The rate value is between 0 and 1 , with 0 meaning 
thatthedata is incompressible. 

The -c flag is used to specify an alternate display mode that shows packet compression statistics: the number of packets and 
bytes uncompressed (that is, before compression or after decompression), compressed, and incompressible (packets that did 
not shrink on compression and were transmitted uncompressed), and the recent compression rate. This rate reflectsthe 
recent performance of the compression code rather than the overall rate the code compression was enabled. 

The -iflag is used to specify the interval between printouts. The default is 5 seconds, 
unit# specifies which interface to use for gathering statistics. 

2 May 1995 


prunehistory 

prunehistory— Remove filenames from U senet history file 

SYNOPSIS 

prunehistory [ -f filename ] [ - p ] [input ] 

DESCRIPTION 

prunehistory modifies the history(5) textfileto remove a set of filenames from it. The filenames are removed by overwriting 
them with spaces so that the size and position of any following entries do not change. 

prunehistory reads the named input file or standard input if no file is given. The input is taken as a set of lines. Blank lines 
and lines starting with a number sign (#) are ignored. All other lines should consist of a M essage-ID followed by zero or more 
filenames, prunehistory usually complains about lines that do not follow this format. If the -p flag is used, then the program 
silently prints any invalid lines on its standard output. (Blank lines and comment lines are also passed through.) This can be 
useful when prunehistory isused as a filter for other programs such as reap. 

T he M essage-ID isused asthedbz(3) key to get an offset into the text file. If no filenames are mentioned on the input line, 
then all filenames in the text are removed. If any filenames are mentioned, they are converted into the history file notation. If 
they appear in the line for the specified M essage-ID, they are removed. 

T he default name of the history fi le is /news/iib/history; to specify a different name use the -f flag. 

Because innd(8) only appends to the text file prunehistory does not need to have any interaction with it. 

It is a good idea to delete purged entries and rebuild thedbz database every so often by using a script such as the following: 

ctlinnd throttle "Rebuilding history database" 
cd /news/lib 
awk 'NF > 2 { 

printf "%s\t%s\t%s",$1,$2,$3; 
for (i = 4; i <= NF; i++) 
printf " %s", $i; 
print 11 \n"; 

}' <history >history.n 
if makehistory -r -f history.n ; then 



quotacheck 


1371 


mv history.n history 
mv history.n.pag history.pag 
mv history.n.dir history.dir 
else 

echo 'Problem rebuilding history; old file not replaced 1 
fi 

ctlinnd go "Rebuilding history database" 

N otethat this keeps no record of expired articles. 

HISTORY 

W ritten by Rich $alz (nsaiz@uunet.uu.net) for InterN etN ews. 

SEE ALSO 

dbz(3), history(5), innd(8) 

quotacheck 

quotacheck— Scan a filesystem for disk usages. 

SYNOPSIS 

quotacheck [-g] [-u] [-v] -a 
quotacheck [-g] [-u] [-v] filesys ... 

DESCRIPTION 

quotacheck performs a filesystem scan for usage of files and directories, used by either user or group. The output is the quota 
fi le for the correspond! ng fi lesystem. By default, the names for these fi les are 

A user Scan quota.user 

A group scan quota.group 

T he resulting fi le consists of a struct dqbik for each possible ID up to the highest existing U ID orGID and containsthe 
values for the disk file and block usage and possibly excess time for these values. (For definitions of struct dqbik, see 

linux/quota.h.) 

quotacheck should be run each time the system boots and mounts non-val id filesystems. This is most likely to happen after a 
system crash. 

The speed of the scan decreases with the amount of directories increasing. The time needed doubles when disk usage is 
doubled as well. A 100M B partition used for 94 percent is scanned in one minute; the same partition used for 50 percent is 
done in 25 seconds. 

OPTIONS 

-v This way, the program will give some useful information about what it is doing, plus 

some fancy stuff. 

-d This means debug. It will result in a lot of information that can be used in debugging 

the program. The output is very verbose and the scan will not be fast. 

-u This flag tel Is the program to scan thedisk and to count the files and directories used by 

a certain U ID. This is the default action. 

-g This flag forces the program to count the files and directories used by a certain GID. 

NOTE 

checkquota should only be run as superuser. N on-privileged users are presum ably not allowed to read all the directories on 
the given filesystem. 
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SEE ALSO 

quota(l), quotactl(2), fstab(5), quotaon(8), quotaoff(8), edquota(8), nepquota(8), fsck(8), efsck(8), e2fsck(8), xfsck(8) 

FILES 

quota.user- 
quota.group 
/etc/fstab 

AUTHOR 

Edvard Tuinder (v892231@si.hhs.nl, etuinder@delirium.nl.mugnet.org), M afCO van Wieringen (v892273@si.hhs.nl, 
mvw@mcs.nl.mugnet.org). 

21 August 1993 


quotaon,quotaoff 

quotaon, quotaof t—Turn filesystem quotas on and off. 

SYNOPSIS 

/usr/etc/quotaon [ -vug ] filesystem... 
/usr/etc/quotaon [ -avug ] 

/usr/etc/quotaoff [ -vug ] filesystem... 
/usr/etc/quotaoff [ -avug ] 


DESCRIPTION 

quotaon announces to the system that disk quotas should be enabled on one or more filesystems. The filesystem quota files 
must be present in the root directory of the specified filesystem and be named quota.user for user quota or quota.group for 
group quota. 

quotaof f announces to the system that filesystems specified should have any disk quotas turned off. 


OPTIONS 

quotaon 


quotaoff 


-a 

-v 

-u 


All filesystems in /etc/fstab marked read-write with quotas will have their quotas 
turned on. T his is usually used at boottimeto enablequotas. 

D i splay a message for each filesystem where quotas are turned on. 

M anipulate user quotas. T his is the default. 

M anipulate group quotas. 


Forceall filesystems in /etc/fstab to have their quotas disabled. 
D isplay a message for each filesystem affected. 

M anipulate user quotas. This isthe default. 

M anipulate group quotas. 


FILES 


quota.user 
quota.group 
/etc/fstab 


U ser quota file at the filesystem root 
G roup quota file at the filesystem root 
Default filesystems 
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SEE ALSO 

quotactl(2), fstab(5) 


8 Junel993 


rarp 

rarp— M ani pulate the system RARP table 

SYNOPSIS 

rarp [-v] [-t type] -a [hostname] 
rarp [-v] -d host name ... 
rarp [-v] [-t type] -s hostname hw_addr 

DESCRIPTION 

rarp manipulates the kernel's RARP table in various ways. The primary options are clearing an address mapping entry and 
manually setting up one. For debugging purposes, the rarp program also allows a complete dump of the RARP table. 

OPTIONS 

-V 

-t type 

-a [host name ] 

-d host name 
-s host name hw_addr 

FILES 

/proc/net/rarp 

AUTHORS 

ROSS D . M artin (martin@trcsun3.eas.asu.edu), Fred N . van Kempen (waitje@uwalt. nl.mugnet.org). 

11Junel994 


Tell theuserwhatisgoingon by being verbose. 

When setting or reading the RARP table, this optional parameter tells rarp which class 
of entries it should check for. The default value of this parameter is ether (hardware 
code 0x01 for IEEE 802.3 10M bps Ethernet). Other values might include network 
technologies such as AX .25 (ax 2 s). 

Showsthe entries of thespecified hosts. If th e h o s t n a me parameter isnotused, all entries 
are displayed. 

Remove the entries of thespecified host. T his can be used if the indicated host is 
brought down, for example 

Create an RARP address mapping entry for host host name with hardware address set to 
hw_ add r class, but for most classes, you can assume that the usual presentation can be 
used. For the Ethernet class, this is 6 bytes in hexadecimal, separated by colons. 


rdev 

rdev— Query/set image root device, swap device, RAM disk size, or video mode. 

SYNOPSIS 

rdev [ -rsvh ] [ -o offset ][image [ value [ offset ]]] 
rdev [ -o offset ][ i mage [ root_device [ offset ]]] 
swapdev [ -o offset ][i mage [ swap_device [ offset ]]] 

ramsize [ -o offset ][i mage [ size [ offset ]]] 

vidmode [ -o offset ][i mage [ mode [ offset ]]] 

rootflags [ -o offset ][image [ flags [ offset ]]] 
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DESCRIPTION 

With no arguments, rdev outputs an /etc/mtab linefor the current root filesystem. With no arguments, swapdev, ramsize, 
vidmode, and rootfiags print usage information. 

In a bootable image for the Linux kernel, there are several pairs of bytes that specify the root device, the video mode the size 
of the RAM disk, and the swap device. These pairs of bytes, by default, begin at offset 504 (decimal) in the kernel image: 

498 Rootfiags 
(500 and 502 Reserved) 

504 RAM Disk Size 
506 VGA Mode 
508 Root Device 
(510 Boot Signature) 

rdev changes these values. 

Typical values for the image parameter, which is a bootable Linux kernel image, are as follows: 

/vmlinux 

/vmlinux.test 

/vmunix 

/vmunix.test 

/dev/fd0 

/dev/fdl 

When using the rdev or swapdev commands, the root device or swap device parameter are as follows: 

/dev/hda[1-8] 

/dev/hdb[1-8] 

/dev/sda[1-8] 

/dev/sdb[1-8] 

For the ramsize command, the size parameter specifies the size of the RAM disk in kilobytes. 

For the rootfiags command, thef lags parameter contains extra information used when mounting root. Currently, the only 
effect of these flags is to force the kernel to mount the root filesystem in read-only mode iff 1 ags isnonzero. 

Forthevidmode command, the mode parameter specifies the video mode: 

-3 Prompt 

-2 Extended VGA 

-1 Normal VGA 

0 As if 0 was pressed at the prompt 

1 As if 1 was pressed at the prompt 

2 As if 2 was pressed at the prompt 

n As if n was pressed at the prompt 

If the value is not specified, the image is exami ned to determine the current setti ngs. 


OPTIONS 


•S 

Causes rdev to act like swapdev. 

-r 

Causes rdev to act like ramsize. 

-R 

Causes rdev to act like rootfiags. 

-V 

C auses rdev to act 1 ike vidmode. 

-h 

Provides help. 



renice 

BUGS 

For historical reasons, there are two methods for specifying alternative values for the offset. 

The user interface is cumbersome, non-intuitive, and should probably be rewritten from scratch, allowing multiple kernel 
image parameters to be changed or examined with a single command. 

If LILO isused, rdev isno longer needed for setting the root device and theVGA mode because the parameters that rdev 
modifies can beset from theULO prompt during a boot. However, rdev is still needed at thistimefor setting the RAM disk 
size. Users are encouraged to find the LILO documentation for more information and to use LILO when booting their 
systems. 

AUTHORS 

Originally by Werner Almesberger (aimesberianessie.es.id.ethz.ch). M odified by Peter M acDonald 
(pmacdona@sanj uan.UVic.CA). rootflags Support added by Stephen T weedie (sct@dcs.ed.ac.uk). 

Linux0.99, 20 November 1993 

renice 

renice— Alter priority of running processes. 

SYNOPSIS 

renice priority [[- p] p i d ...] [[ -g] pgrp ...] [[ - u ] user ...] 

DESCRIPTION 

renice alters the scheduling priority of one or more running processes. T he following "who" parameters are interpreted as 
process IDs, process group IDs, or user names, reniceing a process group causes all processes in the process group to have 
their scheduling priority altered, reniceing a user causes all processes owned by the user to have their scheduling priority 
altered. By default, the processes to be affected are specified by their process IDs. 

0 ptions supported by renice: 

-g Forcewho parameters to be interpreted as process group IDs. 

-u Forcethewho parameters to be interpreted as usernames. 

-p Reset the who interpretation to be (the default) process IDs. 

The following example changes the priority of process ID s 987 and 32 and all processes owned by users daemon and root: 

renice +1 987 -u daemon root -p 32 

Users other than the superuser can only alter the priority of processes they own and can only monotonically increase their 
"nice value" within therangeo to prio_max ( 20 ). (This prevents overriding administrative fiats.) The superuser can alter the 
priority of any process and set the priority to any value in the range priojiin (- 20 ) to prio_max. Useful priorities are 20 (the 
affected processes run only when nothing else in the system wants to), 0 (the "base" scheduling priority), and anything 
negative (to make things go very fast). 

FILES 

/etc/passwd to map usernames to user IDs 

SEE ALSO 

getpriority(2), setpriority(2) 

BUGS 

N on-superusers cannot increase scheduling priorities of their own processes, even if they were the ones that decreased the 
priorities in the first place. 
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HISTORY 

Therenice command appeared in BSD 4.0. 


BSD 4, 9Junel993 


repquota 

repquota — Summarize quotas for a filesystem. 

SYNOPSIS 

/usr/etc/repquota [ -vug ] filesystem... 

/usr/etc/repquota [ -avug ] 

DESCRIPTION 

repquota prints a summary of the disk usage and quotas for the specified filesystems. For each user, the current number of 
files and amount of space (i n kilobytes) is printed, alongwith any quotas created with edquota(8). 

OPTIONS 

-a Report on all filesystems indicated in /etc/fstab to beread-writewith quotas. 

-v Report all quotas even if there is no usage. 

-g Report quotas for groups. 

- u R epo rt qu otas for u sers. T h i s i s th e defau 11. 

0 nly the superuser can view quotas that are not their own. 

FILES 

quotas Quota file at the filesystem root 

/etc/fstab D efault filesystems 

SEE ALSO 

quota(l), quotactl(2), edquota(8), quotacheck(8), quotaon(8) 

8Junel993 


rexecd 

rexecd— Remote execution server. 

SYNOPSIS 

rexecd 

DESCRIPTION 

rexecd is the server for the rexec(3) routine. The server provides remote execution facilities with authentication based on 
usernames and passwords. 

rexecd listens for service requests at the port indicated in the exec service specification; seeservices(5). W hen a service 
request is received, thefollowing protocol isinitiated: 

1. The server reads characters from the socket up to a null \® byte. The resultant string is interpreted as an ASCII number, 
base 10. 
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2. If the number received in Step 1 is nonzero, it is interpreted as the port number of a secondary stream to be used for the 
stdem. A second connection is then created to the specified port on the client's machine 

3. A null-terminated username of at most 16 characters is retrieved on theinitial socket. 

4. A null-terminated, unencrypted password of at most 16 characters is retrieved on theinitial socket. 

5. A null-terminated command to be passed to a shell is retrieved on theinitial socket. The length of the command is 
limited by the upper bound on the size of the system's argument list. 

6. rexecd then validates the user as is done at login time and, if the authentication was successful, changes to the user's 
home directory and establishes the user and group protections of the user. If any of these steps fail, the connection is 
aborted with a diagnostic message returned. 

7. A null byte is returned on theinitial socket and the command line is passed to the normal login shell of the user. The 
shell inherits the network connections established by rexecd. 


DIAGNOSTICS 


Except for the last one listed, all diagnostic messages are returned on theinitial socket, after which any network connections 
are closed. An error isindicated by a leading byte with a valueof i (u is returned in Step 7 upon successful completion of all 
the steps prior to the command execution). 


username too long 
password too long 
command too long 

Login incorrect. 

No remote directory. 
Try again. 

<s h e I I n a me >: ... 


T he name is longer than 16 characters. 

T he password is longer than 16 characters. 

Thecommand linepassed exceeds the size of theargument list (as configured into the 
system). 

N o password file entry for the username existed or the wrong password was supplied. 
Thechdir command to the home directory failed. 

A fork by the server fai led. 

The user's login shell could not be started. This message is returned on the connection 
associated with the stdem and is not preceded by a flag byte 


SEE ALSO 

rexec(3) 

BUGS 

A facility to allow all data and password exchanges to be encrypted should be present. 

HISTORY 

The rexecd command appeared in BSD 4.2. 

BSD 4.2,16 March 1991 


rlogind 

riogind— Remote login server. 

SYNOPSIS 

rlogind [-aln] 

DESCRIPTION 

riogind is the server for the riogin(l) program. The server provides a remote login facility with authentication based on 
privileged port numbers from trusted hosts. 
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0 ptionssupported by riogind: 

-a Ask hostname for verification. 

-l Prevent any authentication based on the user's .rhosts file unless the user is logging in 

as the superuser. 

- n D i sabl e keep- al i ve m essages. 

riogind listens for service requests at the port indicated in the "login" service specification; seeservices(5). When a service 
request is received, thefollowing protocol is initiated: 

1. The server checks the client's source port. If the port is not in the range 512-1023, the server aborts the connection. 

2. Theserver checks the client's source address and requests the corresponding hostname (seegethostbyaddr(3), hosts(5), 
and named(8)). If the hostname cannot be determi ned, the dot-notation representation of the host address is used. If the 
hostname is in the same domain as the server (according to the last two components of the domain name), or if the -a 
option is given, the addresses for the hostname are requested, verifying that the name and address correspond. N ormal 
authentication isbypassed if theaddressverification fails. 

Once the source port and address have been checked, riogind proceeds with the authentication process described in rshd(8). 

It then allocates a pseudo terminal (see pty(4)) and manipulates file descriptors so that the slave half of the pseudo terminal 
becomes the stdin, stdout, and stderr for a login process. The login processisan instance of theiogin(l) program, invoked 
with the -t option if authentication has succeeded. If automatic authentication fails, the user is prompted to log in as if on a 
standard terminal line. 

The parent of the login process manipulates the master side of the pseudo terminal, operating as an intermediary between the 
login process and th^client instance of the riogin program. In normal operation, the packet protocol described in pty(4) is 
invoked to provide S/Q type facilities and propagate interrupt signals to the remote programs. The login process propagates 
the client terminal's baud rate and terminal type, as found in the environment variable term; see environ(7). The screen or 
window size of the terminal is requested from the client, and window size changes from the client are propagated to the 
pseudo terminal. 

T ran sport-level keep-alive messages are enabled unless the -n option is present. The use of keep-alive messages allows sessions 
to be timed out if the client crashes or becomes unreachable. 

DIAGNOSTICS 

All initial diagnostic messages are indicated by a leading byte with a value of i, after which any network connections are 
closed. If there are no errors before login is invoked, a null byte is returned as in indication of success. 

my again. A fork by the server fai led. 

SEE ALSO 

login(l), ruserok(3), rshd(8) 

BUGS 

The authentication procedure used here assumes the integrity of each client machine and the connecting medium. This is 
insecure but is useful in an "open" environment. 

A facility to allow all data exchanges to be encrypted should be present. 

A more extensible protocol should be used. 

HISTORY 

The riogind command appeared in BSD 4.2. 



BSD 4.2,16 March 1991 
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route 

route— Show/manipulate the IP routing table. 

SYNOPSIS 

route [ -vn ] 

route [ -v ] add [ -net | -host ] XXXX [gw 6GGG] [metric MMMM] [netmask NNNN] 

[mss NNNN] [window NNNN] [dev DDDD] 
route [ -v ] del XXXX 

DESCRIPTION 

route manipulates the kernel's IP routing table. Itsprimary use isto set up static routes to specific hosts or networks via an 
interface after it has been configured with theifconfig(8) program. This version of route is intended solely for use with 
kernel versions 0.99pll4n and newer kernels. 

OPTIONS 

(none) Prints out the kern el routing table, listing destination address, gateway, netmask for 

route ("Gen mask"), flags (u =U p, h = H ost, g = Gateway, d = dynamic, m = M odified), 
Metric (currently not supported), Ref, use, and if ace (which device the route maps to). 

-n Same as previous but shows numerical addresses instead of trying to determine symbolic 

host names. 

-v A flag for verbose (not actually used). 

del xxxx D eletes the route associated with the destination addressxxxx. 

add [ - net | -host ] xxxx [gwGGGG] Adds a route to the IP address xxxx. T he route is a network route if the -net modifier is 

[metric MMMM] [netmask NNNN] used Or XXXX is found in /etc/networks by the getnetbyname( ) library function and no 

[dev oddd] -host modifier is used. 

The gw gggg argument means that any IP packets sent to this address will be routed 
through the specified gateway. N ote The specified gateway must be reachable first. This 
usually means that you have to set up a static route to the gateway beforehand. 
Themetric MMMM modifier is not yet implemented (and with the -v option will actually 
print a warning). 

Thenetmask nnnn modifier specifies the netmask of therouteto be added. This only 
makes sense for a network route and when the addressxxxx actually makes sense with 
the specified netmask. If no netmask is given, route guesses it instead, so for most 
normal setups, you won't need to specify a netmask. 

The mss nnnn modifier specifies the T C P mss for therouteto be added. This is usually 
used only for fine optimization of routing setups. 

The window nnnn modifier specifies the T C P window for therouteto be added. This is 
typically only used on AX.25 networks and with drivers unable to handle back-to-back 
frames—such asthe3c501 orDE600. 

Thedev dddd modifier forces the route to be associated with the specified device because 
the kernel will otherwise try to determinethedeviceon its own (by checking already 
existing routes and device specifications and where the route is added to). In most 
normal networks, you won't need this 

If dev dddd is the last option on the command line, the word dev may be omitted 
because it’s the default. Otherwise the order of the route modifiers (metric, netmask, gw, 
and dev) doesn't matter. 
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EXAMPLES 

route add -net 12 /. 0 . 0.0 Adds the normal loopback entry, using netmask 255 . 0 . 0.0 (C lass A net determined from 

the destination address) and associated with theio device (assuming this device was 
previously set up correctly with tfcont±g(8)). 

route add -net 192.56.76.0 Adds a route to the network 192 .56.76.* via eth@. T he C lass C netmask modifier is not 

netmask 255 . 255 . 255.0 dev eth 0 really necessary here because 192 .* isaClassC IP address. The word dev can be omitted 

here. 

route add default gw mango-gw Adds a default route (which will be used if no other route matches). All packets using 

this route will begatewayed through mango-gw. The device that will actually be used for 
that route depends on how you can reach mango -gw; thestatic route to mango-gw will have 
to be set up before. 

route add ipx4 si 0 route add -net Thiscommand sequence adds the route to theipx4 host viatheSLIP interface 
192 . 57 . 66.0 netmask 255 . 255 . 255.0 (assuming that ipx4 istheSLI P host) and then adds the net 192 . 57 . 66.0 to be gatewayed 
gw ipx4 through that host. 

FILES 

/proc/net/route 

/etc/networks 

/etc/hosts 

SEE ALSO 

ifconfig(8) 

HISTORY 

route for Linux wasori ginally written by Fred N. van Kern pen (waitje 0 uwait.ni.mugnet.org) and then modified by Johannes 
Stilleand LinusT orvaldsfor pll5. Alan Cox added the mss and window options for Linux 1.1.22. 

14Junel994 

routed 

routed— N etwork routing daemon. 

SYNOPSIS 

routed [-d] [-g] [-q] [-s] [-t] [IogfiI e ] 

DESCRIPTION 

routed is invoked at boot time to manage the network routing tables. The routing daemon uses a variant of the Xerox N S 
Routing Information Protocol in maintaining up-to-date kernel routing table entries. It used a generalized protocol capable 
of use with multiple address types but is currently used only for Internet routing within a cluster of networks. 

In normal operation, routed listens on the udp(4) socket for theroute(8) service(seeservices(5)) for routing information 
packets. If the host is an internetwork router, it periodically supplies copies of its routing tables to any directly connected 
hosts and networks. 

When routed is started, it uses the siocgifconf iocti(2) to find those directly connected interfaces configured into the system 
and marked "up" (the software loopback interface is ignored). If multiple interfaces are present, it is assumed that the host 
will forward packets between networks, routed then transmits a request packet on each interface (using a broadcast packet if 
the interface supports it) and entersa loop, listening for request and response packets from other hosts. 
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When a request packet is received, routed formulates a reply based on the information maintained in its internal tables. The 
response packet generated contains a list of known routes, each marked with a "hop count" metric (a count of 16, or greater, 
is considered "infinite”). The metric associated with each route returned provides a metric relative to the sender. 

Response packets received by routed are used to update the routing tables if one of the followi ng conditions is satisfied: 

N o routing table entry exists for the destination network or host, and the metric indicates the destination is "reachable" 
(the hop count is not infinite). 

The source host of the packet is the same as the router in the existing routing table entry. That is, updated information is 
being received from the very internetwork router through which packets for the destination are being routed. 

The existing entry in the routing table has not been updated for some time (defined to be 90 seconds) and the route is at 
least as cost effective as the current route. 

The new route describes a shorter route to the destination than the one currently stored in the routing tables; the metric 
ofthenew route is compared against the one stored in thetableto decide this 

When an update isapplied, routed records the change in its internal tables and updates thekernel routing table. The change 
is reflected in the next response packet sent. 

In addition to processing incoming packets, routed also periodically checks the routing table entries. If an entry has not been 
updated for three minutes, the entry's metric is set to infinity and marked for deletion. Deletions are delayed an additional 
60 seconds to ensure the invalidation is propagated throughout the local Internet. 

H osts acting as internetwork routers gratuitously supply their routing tables every 30 seconds to all directly connected hosts 
and networks The response is sent to the broadcast address on nets capable of that function, to the destination address on 
point-to-point I inks and to the router's own address on other networks. The normal routing tables are bypassed when 
sending gratuitous responses. The reception of responses on each network is used to determine that the network and 
interface are functioning correctly. If no response is received on an interface, another route may be chosen to route around 
the interface, or the route may be dropped if no alternative is available. 

Options supported by routed: 

-d Enable additional debugging information to be logged, such as bad packets received. 

-g This flag is used on internetwork routers to offer a route to the "default" destination. 

T his istypically used on a gateway to the Internet or on agateway that uses another 
routing protocol whose routes are not reported to other local routers. 

-s Supplying this option forces routed to supply routing information whether it is acting as 

an internetwork router or not. This is the default if multiple network interfaces are 
present or if a point-to-point link is in use. 

-q Thisistheoppositeof the -s option. 

-t If the -t option is specified, all packets sent or received are printed on the standard 

output. In addition, routed will not divorce itself from the controlling terminal so that 
interrupts from the keyboard will kill the process. 

Any other argument supplied is interpreted as the name of file in which routed'sactionsshould be logged. This log contains 
information about any changes to the routing tables and, if not tracing all packets, a history of recent messages sent and 
received that are related to the changed route. 

In addition to the facilities described previously, routed supports the notion of "distant" passive and active gateways. W hen 
routed is started, it reads the file to find gateways that might not be located using only information from thesioGiFcoNFiocti 
(2). Gateways specified in this manner should be marked passive if they are not expected to exchange routing information, 
whereas gateways marked active should be willing to exchange routing information (that is, they should have a routed process 
running on the machine). Routes through passive gateways are installed in the kernel's routing tables once upon startup. 

Such routes are not included in any routing information transmitted. Active gateways are treated equally to network 
interfaces. Routing information is distributed to the gateway, and if no routing information is received for a period of the 
time, the associated route is deleted. G ateways marked external are also passive but are not placed in the kernel routing table 
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nor are the/ included in routing updates. The function of external entries is to inform routed that another routing process 
will install such a route and that alternate routes to that destination should not be installed. Such entries are only required 
when both routers might learn of routes to the same destination. 

The /etc/gateways is comprised of a series of lines, each in the following format: 

<netjhost> n a me 1 gateway n a me 2 metric value <passive|active]external> 

The net or host keyword indicates if the route is to a network or specific host. 

n a me 1 is the name of the destination network or host. This can be a symbolic name located in or known to the name server if 
started after named(8) or an Internet address specified in "dot" notation; see inet(3). 

name 2 isthenameor addressof the gateway to which messages should be forwarded, 
value is a metric i ndi cati ng the hop count to the desti nati on host or network. 

One of the keywords passive, active, or external indicates if the gateway should be treated as passive or active (as described 
previously) or whether the gateway is external to the scope of the routed protocol. 

Internetwork routers that are directly attached to theARPAnet or M il net should use the Exterior Gateway Protocol (EG P) to 
gather routing information rather than use a static routing table of passive gateways. EGP is required in order to provide 
routes for local networks to the rest of the Internet system. Sites needing assistance with such configurations should contact 
the Computer Systems Research Group at Berkeley. 

FILES 

/etc/gateways for distant gateways 

SEE ALSO 

udp(4), icmp(4), XNSrouted(8), htable(8) 

Internet Transport Protocols, XSIS 028112, Xerox System Integration Standard 

BUGS 

The kernel's routing tables may not correspond to those of routed when redirects change or add routes, routed should note 
any redirects received by reading the 1C M P packets received via a raw socket. 

routed should incorporate other routing protocols, such as Xerox N S, xNSrouted(8), and EGP . Using separate processes for 
each requires configuration options to avoid redundant or competing routes. 

routed should listen to intelligent interfaces, such as an IM P, to gather more information. It does not always detect 
unidirectional failuresin network interfaces (such aswhen the output side fails). 

HISTORY 

The routed command appeared in BSD 4.2. 

BSD 4.2,16 March 1991 


rpc.rusersd 

rpc. rusersd — Logged-in users server. 

SYNOPSIS 

/usr/libexec/rpc.rusersd 

DESCRIPTION 

rpc.rusersd is a server that returns information about users currently logged into thesystem. 
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The currently logged-in users are queried using therusers(l) command. Therpc.rusersd daemon isusually invoked by 

inetd(8). 

rpc.rusersd USesan RPC protocol defined in /usr/include/rpcsvc. 

SEE ALSO 

rusens(l), who(l), w(l), inetd(8) 

BSD 4.3, 7Junel993 


rpc.rwalld 

rpc. rwaiid — W rite messages to users currently logged in to the server. 

SYNOPSIS 

/usr/libexec/rpc.rwalld 

DESCRIPTION 

rpc.rwalld is a server that will send a message to users currently logged in to the system. This server invokes the waii(l) 
command to actually write the messages to the system. 

Messages are sent to this server by the rwaii(l) command. Therpc.rwaiid daemon isusually invoked by inetd(8). 
rpc.rwalld USesan RPC protocol defined in /usr/include/rpcsvc/rwall.x. 

SEE ALSO 

rwall(l), wall(l), inetd(8) 

BSD 4.3,7Junel993 


rpcinfo 

rpcinfo— Report RPC information. 

SYNOPSIS 

rpcinfo -p [host ] 

rpcinfo [-n port n u m ] -u host program [version] 
rpcinfo [-n port n u m ] -t host program [version] 
rpcinfo -b program version 
rpcinfo -d program version 

DESCRIPTION 

rpcinfo makes an RPC call to an RPC server and reports what it finds. 


OPTIONS 



-p 

Probe the port mapper on host and print a list of all registered RPC programs. If host is 
not specified, it defaults to the value returned by hostname(l). 

-U 

M akean RPC call to procedureO of program on the specified host 
report whether a response was received. 

using U D P and 

-t 

M akean RPC call to procedureO of program on the specified host 
whether a response was received. 

using TCP and report 

-n 

Useportnum as the port number for the -t and -u options instead of the port number 
given by the port mapper. 
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-b M akean RPC broadcast to procedure 0 of the specified program and versi on using U D P 

and report all hosts that respond. 

-d Delete registration for the RPC service of the specified program and versi on. This option 

can be exercised only by the superuser. 

The program argument can be either a name or a number. If a version is specified, rpcinto attempts to call that version of the 
specified program. Otherwise, rpcinfo attempts to find all the registered version numbers for the specified program by calling 
version 0 (which ispresumed notto exist; if it does exist, rpcinto attempts to obtain this information by calling an extremely 
high version number instead) and attempts to call each registered version. N ote that the versi on number is required for -b 
and -d options. 

EXAMPLES 

To show all the RPC services registered on the local machine, use 
rpcinto -p 

T o show all of the RPC services registered on the machine named klaxon, use 
rpcinfo -p klaxon 

T o show all machines on the local net that are running the Yellow Pages service, use 
rpcinfo -b ypserv 'version' -- uniq 

'version 1 is the current Yellow Pages version obtained from the results of the -p switch above. 

T o delete the registration for version 1 of thewaiid service, use 
rpcinfo -d walld 1 

SEE ALSO 

rpc(5), portmap(8), RPC Programming G uide 

BUGS 

In releases prior to SunOS 3.0, theN etwork File System (N FS) did not register itself with the port mapper; rpcinfo cannot 
be used to makeRPC calls to theN FS server on hosts running such releases. 

17 December 1987 


rquotad,rpc.rquotad 

rquotad, rpc.rquotad— Remote quota server. 

SYNOPSIS 

/usr/etc/rpc.rquotad 

DESCRIPTION 

rquotad is an rpc(3N ) server that returns quotas for a user of a local filesystem that is mounted by a remote machine over the 
N FS. The results are used by quota(l) to display user quotas for remote filesystems. The rquotad daemon is usually started at 
boot time from therc.net script. 

FILES 

quotas Quota file at the filesystem root 

SEE ALSO 

quota(l), rpc(3N ), nfs(4P), services(5) inetd(8C) 


17 December 1987 
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rshd— Remote shell server. 

SYNOPSIS 

rshd [-alnL] 


DESCRIPTION 

The rshd server is the server for the rcmd(3) routine and, consequently, for the rsh(l) program. The server provides remote 
execution facilities with authentication based on privileged port numbers from trusted hosts. 

The rshd server listens for service requests at the port indicated in thecmd service specification; seeservices(5). When a 
service request isreceived, the following protocol isinitiated: 

1. The server checks the client's source port. If the port is not in the range 512-1023, the server aborts the connection. 

2. The server reads characters from the socket up to a null (\m) byte. The resultant string is interpreted as an ASCII 
number, base 10. 

3. If the number received in Step 2 is nonzero, it is interpreted as the port number of a secondary stream to be used for the 
stdem. A second connection is then created to the specified port on the client's machine. The source port of this second 
connection is also in the range 512-1023. 

4. Theserver checks the client's source address and requests the corresponding hostname (seegethostbyaddr(3), hosts(5), 
and named(8)). If the hostname cannot be determi ned, the dot-notation representation of the host address is used. If the 
hostname is in the same domain as the server (according to the last two components of the domain name), or if the -a 
option is given, the addresses for the hostname are requested, verifying that the name and address correspond. If address 
verification fails, the connection is aborted with the message, Host address mismatch. 

5. A null-terminated username of at most 16 characters is retrieved on the initial socket. This username is interpreted as 
the user identity on the client's machine. 

6 . A null-terminated username of at most 16 characters is retrieved on theinitial socket. This username is interpreted asa 
user identity to useon the server's machine. 

7. A null-terminated command to be passed to a shell is retrieved on theinitial socket. The length of the command is 
limited by theupper bound on the size of the system's argument list. 

8 . rshd then validates the user using ruserok(3), which uses the file and the file found in the user's home directory. The -i 
option pre/ents ruserok(3) from doing any validation based on theuser's. nhosts file, unlesstheuser isthe superuser. 

9. A null byte is returned on theinitial socket and the command line is passed to the normal login shell of theuser. The 
shell inherits the network connections established by rshd. 

T ran sport-level keep-alive messages are enabled unless the -n option is present. The use of keep-alive messages allows sessions 
to be timed out if the client crashes or becomes unreachable. 

The -l option causes all successful accesses to belogged to sysiogd(8) asauth.info messages and all failed accesses to be 
logged as auth.notice. 


DIAGNOSTICS 


Except for the last one listed, all diagnostic messages are returned on theinitial socket, after which any network connections 
are closed. An error isindicated by a leading byte with a value of i (u is returned in Step 9 upon successful completion of all 
thestepsprior to theexecution of thelogin shell). 


Locuser too long. 
Ruser too long. 
Command too long. 

Login incorrect. 
Remote directory. 


The name of theuser on theclient'smachineislongerthan 16 characters. 

T he name of the user on the remote machine is longer than 16 characters. 
Thecommand linepassed exceedsthesizeof theargument list (asconfigured into the 
system). 

N o password file entry for the username existed. 

Thechdir command to the home directory failed. 
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Permission denied. 

Can't make pipe. 

Can't fork; try again 
<s h e I I n a me >: ... 

SEE ALSO 

rsh(l), rcmd(3), ruserok(3) 

BUGS 

The authentication procedure used here assumes the integrity of each client machine and the connecting medium. This is 
insecure but is useful in an "open" environment. 

A facility to allow all data exchanges to be encrypted should be present. 

A more extensible protocol (such asT elnet) should be used. 

BSD 4.2, 30 April 1991 

rwhod 

rwhod — System status server. 

SYNOPSIS 

rwhod 

DESCRIPTION 

rwhod istheserver that maintainsthedatabaseused bytherwho(l) and ruptime(l) programs. Itsoperation ispredicated on 
the ability to broadcast messages on a network. 

rwhod operates as both a producer and consumer of status information. As a producer of information, it periodically queries 
the state of the system and constructs status messages that are broadcast on a network. As a consumer of information, it 
listens for other rwhod servers' status messages, validating them and then recording them in a collection of files located in the 
directory. 

The server transmits and receives messages at the port indicated in therwho service specification; seeservices(5). The 
messages sent and received are of the form: 
struct outmp { 

char out_line[8]; /* tty name */ 
char out_name[8]; /* user id */ 
long out_time; /* time on */ 

}; 

struct whod { 

char wd_vers; 
char wd_type; 
char wd_fill[2]; 

int wd_sendtime; 
int wd_recvtime; 
char wd_hostname[32]; 
int wd_loadav[3]; 
int wd_boottime; 
struct whoent { 

struct outmp wejjtmp; 


The authentication procedure described previously failed. 

T he pi pe needed for the stderr wasn't created. 

A fork by the server fai led. 

The user's login shell could not be started. This message is returned on the connection 
associated with the stderr and is not preceded by a flag byte. 
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int we_idle; 

} wd_we[1024 / sizeof (struct whoent)]; 

}; 

All fields are converted to network byte order prior to transmission. The load averages are as calculated by thew(l) program 
and represent load averages over the 5-, 10-, and 15-minute intervals prior to a server's transmission; they are multiplied by 
100 for representation in an integer. The hostname included is that returned by thegethostname(2) system call, with any 
trailing domain name omitted. The array at the end of the message contains information about the users logged in to the 
sending machine. This information includes the contents of the utmp(5) entry for each non-i die terminal line and a value 
indicating the time in seconds since a character was last received on the terminal line 

M essages received by therwho server are discarded unless they originated at an rwho server's port. In addition, if the host's 
name, as specified in the message, contains any unprintable ASCI I characters, the message is discarded. Valid messages 
received by rwhod are placed in files named in the directory. These files contain only the most recent message, in the format 
described previously. 

Status messages are generated approximately once every threeminutes. rwhod performs an niist(3) every 30 minutes to guard 
against the possibility that thisfile is not the system image currently operating. 

SEE ALSO 

rwho(l), ruptime(l) 

BUGS 

There should be a way to relay status information between networks. Status information should be sent only upon request 
rather than continuously. People often interpret the server dying or network communication failures as a machine going 
down. 

HISTORY 

The rwhod command appeared in BSD 4.2. 

BSD 4.2,16 March 1991 
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sendmaii— Send mail over the Internet. 

SYNOPSIS 

sendmail [flags] [address ...] 

newaliases 

mailq [-v] 

smtpd 

bsmtp 

runq 

DESCRIPTION 

sendmaii sends a message to one or more recipients, routing the message over whatever networks are necessary, sendmaii does 
internetwork forwarding as necessary to deliver the message to the correct place. 

sendmaii is not intended as a user interface routine. Other programs provide user-friendly front ends, sendmaii is used only to 
deliver preformatted messages. 

With no flags, sendmaii reads its standard input up to an end-of-fileor a line consisting only of a single dot and sends a copy 
of the message found thereto all the addresses listed. It determines the networks to use based on the syntax and contents of 
the addresses. 
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Local addresses are looked up in afileand aliased appropriately. Aliasing can be prevented by precedingtheaddresswith a 
backslash. Usually, the sender is not included in any alias expansions; for example, if john sends to group and group includes 
john in the expansion, then the letter will not be delivered to john. 


Flags are 
-ba 


-bd 


-bi 

-bn 

-bp 

-bs 

-bb 

-bt 

-bv 

-bz 

-C f i I e 

-d X 

- F f u 11 n a me 
-f name 

-h N 


-n 

-o x val ue 
-q t i me 


-M i dent 
-R addr 
-S addr 
-r name 
-t 


Go into ARPAN ET mode. All input lines must end with a C R-LF, and all messages will 
be generated with aCR-LF attheend. Also, theFrom: and Sender: fields are examined 
for the name of the sender. 

Run as a daemon. This requires Berkeley I PC. sendmaii will fork and run in the 
background, listening on socket 25 for incoming SM TP connections This is usually run 
from /etc/rc. 

Initialize the alias database. 

Deliver mail in the usual way (default). 

Print a listing of the queue. 

UsetheSM TP protocol as described in RFC 821 on standard input and output. This 
flag implies all the operations of the -ba flag that are compatiblewith SMTP. 

Read batched SMTP (BSMTP) commands from standard input. 

Run in address test mode. This mode reads addresses and shows the steps in parsing; it is 
used for debugging configuration tables. 

Verify names only; do not try to collect or deliver a message. Verify mode is usually used 
for validating users or mailing lists. 

Create the configuration freeze file. 

U se alternate configuration file, sendmaii refuses to run as root if an alternate configura¬ 
tion file is specified. Thefrozen configuration file is bypassed. 

Set debugging value to x. 

Set the full name of the sender. 

Sets the name of the "from" person (thesenderof themail). -f can only beused by 
trusted users (usually root, daemon, and network) or if the person you are trying to 
become is the same as the person you are. 

Set the hop count to n. The hop count is incremented every time the mail is processed. 
When it reaches a limit, themail is returned with an error message, thevictim of an 
aliasing loop. If not specified, Received: lines in the message are counted. 

Don't do aliasing. 

Set option x to the specified «ai ue. Options are described later in this section. 

Processed saved messages in the queue at given intervals. If ti me is omitted, process the 
queue once ti me is given as a tagged number, with s being seconds, m being minutes, h 
being hours, d being days, and w being weeks. For example, -qih30m or -q90m both set the 
timeout to 1 hour, 30 minutes. If ti me isspecified, sendmaii runsin background. This 
option can beused safely with -bd. 

Process the queued message with thequeuelD i dent. 

Process the queued messages that have the string addr in one of the recipient addresses. 
Process the queued messages that have the string addr in the sender address. 

An alternate and obsolete form of the -t flag. 

Read message for recipients. T o:, Cc:, and Bcc: lines are scanned for recipient addresses. 
TheBcc: line is deleted before transmission. Any addresses in the argument list are 
suppressed; that is, they do not receive copies even if listed in the message header. 

Go into verbose mode. Alias expansions are announced and so on. 
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There are also a number of processing options that can beset. Usually, these will only be used by a system administrator. 
Options can beset either on the command line using the -o flag or in the configuration file. These are described in detail in 
the Sendmail I nstallation and 0 peration G uide. T he opti ons are 


A file 
c 

d x 


D 


F mode 
f 

g N 

H f i I e 
i 

k N 


Q queuedi r 
r t i me o u t 


S 


file 


Use alternate alias file. 

On mailers that are considered "expensive" to connect to, don't initiate immediate 
connection. This requires queuing. 

Set the delivery mode to x. Delivery modes arei for interactive (synchronous) delivery, 
b for background (asynchronous) delivery, and q for queue only (actual delivery is done 
the next time the queue is run). 

Try to automatically rebuild the alias database if necessary. 

Set error processing to mode x. Valid modes are m to mail back the error message, w to 
"write” back the error message (or mail it back if the sender is not logged in), p to print 
the errors on theterminal (default), q to throw away error messages (only exit status is 
returned), and e to do special processing for the BerkN et. If the text of the message is 
not mailed back by modes m or w and if the sender is local to this machine, a copy of the 
message is appended to thefilein the sender's home directory. 

The mode to use when creating temporary files. 

SaveU N IX-styleFrom: lines at the front of messages. 

The default group ID to use when calling mailers. 

TheSM TP help file 

Do not take dots on a line by themselves as a message terminator. 

Checkpoint the queue file after every n successful deliveries (default is 10 ). This avoids 
excessive duplicate deliveries when sending to long mailing lists interrupted by system 
crashes. 

The log level. 

Send also to "me” (the sender) if I am in an alias expansion. 

If set, this message may have old style headers. If not set, this message is guaranteed to 
have new style headers (commasinstead of spaces between addresses). If set, an adaptive 
algorithm is used that will correctly determine the header format in most cases. 

Select thedirectory in which to queue messages. 

Thetime-out on reads; if none is set, sendmail will wait forever for a mailer. Thisoption 
violates the word (if not the intent) of the SMTP specification, so the t i me out should 
probably be fairly large. 

Save statistics in the named file. 


S 

T t i me 


t stz, dtz 


Always instantiate the queue file, even under circumstances where it is not strictly 
necessary. This provides safety against system crashes during delivery. 

Set thetime-out on undelivered messages in the queue to the specified time. After 
delivery has failed (for example, because of a host being down) for this amount of time, 
failed messages will be returned to the sender. The default is three days. 

Set the name of thetimezone. 


u user database If set, a user database is consulted to get forwarding information. You can consider this 

an adjunct to the aliasing mechanism, except that the database is intended to be 
distributed; aliases are local to a particular host. This might not be available if your 
sendmail does not have the userdb option compiled in. 
un Set the default user ID for mailers. 


w If not set, name server lookups will use a query type of any to find types cname, a, and mx 

and will cause all existing records to be cached by the local server. If there is (or might 
be) a wildcard mx in the local domain or its parents that are searched, you must set this 
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option, which uses a query type of cname only; otherwise, it causes all fully qualified 
names to match as names in the local domain. 


In aliases, the first character of a name can be a vertical bar to cause interpretation of the rest of the name as a command to 
pipe the mail to. It might be necessary to quote the name to keep sendmaii from suppressing the blanks between arguments. 
For example, a common alias is 
msgs: " |/usr/bin/msgs -s" 

Aliases can also have the syntax to ask sendmaii to read the named file for a list of recipients. For example, an alias such as 
poets: ":include:/usr/local/lib/poets.list" 


would read for the list of addresses making up the group. 

sendmaii returns an exit status describing what it did. The codes are defined in sysexits.h: 


EX_OK 
EX_N0USER 
EXJJNAVAILABLE 
EX_SYNTAX 
EX_SOFTWARE 
EX_OSERR 
EX_N0H0ST 
EX TEMPFAIL 


Successful completion on all addresses. 

U sername not recognized. 

C atchall meaning necessary resources were not avai lable. 
Syntax error in address. 

Internal software error, including bad arguments 
T emporary operating system error, such as cannot fork. 
H ostname not recognized. 

M essage could not be sent immediately but was queued. 


If invoked as newaiiases, sendmaii rebui Ids the alias database. If invoked asmaiiq, sendmaii prints the contents of the mail 
queue. If invoked assmtpd, sendmaii forks and runs as a daemon. If invoked asbsmtp, sendmaii processes batched SMTP on 
standard input. If invoked as rung, sendmaii runs through the mail queueand makes what deliveries are possible. 


FILES 

Except for the file /etc/sendmaii. cf itself, the following pathnames are all specified in /etc/sendmaii.cf.Thus, these values 
areonly approximations. 

/etc/aiiases raw data for alias names 


/etc/aliases.pag 

/etc/aiiases. dir database of alias names 
/etc/sendmaii.cf configuration file 
/etc/sendmaii.tc frozen configuration 
/etc/sendmail.hf help file 
/var/log/sendmail.st collected Statistics 
/var/spool/mqueue/* temp files 


SEE ALSO 

binmaii(l), maii(l), rmaii(l), sysiog(3), aiiases(5), maiiaddr(7), rc(8); D ARPA I nternet Request for C omments RFC 819, 
RFC 821, RFC 822; "Sendmaii: An Internetwork M ail Router," SM M and N o,16, "Sendmaii Installation and Operation 
Guide," SM M and N o.7. 


HISTORY 

The sendmaii command appeared in BSD 4.2. 


BSD 4, 5 August 1991 
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setfdprm 

setfdprm — Sets user-provided floppy disk parameters. 

SYNOPSIS 

setfdprm [ -p ] device name 

setfdprm [ -p ] device size sectors heads tracks stretch gap rate sped fmt_gap 

setfdprm [ -c ] device 

setfdprm [ -y ] device 

setfdprm [ -n ] device 


DESCRIPTION 

setfdprm is a uti lity that can be used to load disk parameters into the auto-detecting floppy devices, to clear old parameter 
sets, and to disable or enable diagnostic messages. 

Without any options, setfdprm loads the device (usually /dev/fdo or /dev/fdi) with a new parameter set with the name entry 
found in /etc/fdprm (usually named 360/360 and so on). These parameters stay in effect until themedia ischanged. 


OPTIONS 

- p device n a me 


-c device 
-y device 
-n device 


Permanently loads a new parameter set for the specified auto-configuring floppy device 
for the configuration with name in /etc/fdprm. Alternatively, the parameters can be given 
directly from the command line. 

Clears the parameter set of the specified auto-configuring floppy device. 

Enables format detection messages for the specified auto-configuring floppy device. 

D isables format detection messages for the specified auto-configuring floppy device. 


BUGS 

This documentation is grossly incomplete. 

FILES 


/etc/fdprm 


AUTHOR 

W emer Almesberger (almesber@nessie.cs.id.ethz.ch) 


Linux 0.99, 20 N ovember 1993 


setserial 

setseriai— Get/set Linux serial port information. 

SYNOPSIS 

setserial [ -abqvVW ] device [ parameterl [ arg ] ] ... 
setserial -g [ -abv ] devicel ... 

DESCRIPTION 

setserial isaprogram designed to set or report the configuration information associated with aserial port. This information 
includes what I/O port and IRQ a particular serial port is using, whether the break key should be interpreted as the Secure 
Attention Key, and so on. 

During the normal bootup process, only COM ports 1-4 are initialized, using the default I/O portsandIRQ values, as 
listed. T o initialize any additional serial ports, or to change the COM 1-4 ports to a nonstandard configuration, the 
setserial program should be used. Typically, it is cal led from an rc. serial script, which is usually run out of /etc/rc. local. 
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Thedeviceargument or arguments specify the serial device that should be configured or interrogated. It will usually have the 
following form: /dev/cua[0-3]. 

If no parameters are specified, setseriai prints the port type (such as 8250,16450,16550,16550A), the hardware I/O port, 
the hardware IRQ line, its "baud base," and someof its operational flags. 

If the -g option is given, the arguments to setseriai are interpreted as a list of devices for which the characteristics of those 
devices should be printed. 

Without the -g option, thefirst argument to setseriai isinterpreted as the device to be modified or characteristics to be 
printed, and any additional arguments are interpreted as parameters that should be assigned to that serial device. 

For the most part, superuser privilege is required to set the configuration parameters of a serial port. A few serial port 
parameters can beset by normal users, however, and these are noted as exceptions in this manual page. 


OPTIONS 


setseriai accepts the following options: 


-a 

-b 


-q 

-v 

-V 

-w 


When reporting the configuration of aserial device print all available information. 
When reporting the configuration of aserial device print a summary of the device's 
configuration, which might be suitable for printing during the bootup process during 
the /etc/rc script. 

Be quiet, setseriai will print fewer lines of output. 

Beverbose. setseriai will print additional status output. 

D isplay version and exit. 

Do wild interrupt initialization and exit. 


PARAMETERS 


T he following parameters can be assigned to a serial port. 

All argument values are assumed to be in decimal unless preceded byex. 


port portnumber 
irq i r q_number 
uart uarttype 


autoconfig 


Theport option sets the I/O port as described previously. 

T he irq option sets the hardware IRQ as described previously. 

This option is used to set the UART type. The permitted types are none, 8250,16450, 
16550, and 16550A. Because the 8250 and 16450 UARTsdo not haveFIFOs, and 
because the original 16550 have bugs that maketheFIFOsunusable the FIFO will only 
be used on chips identified asl6550A UARTs. Setting theUART type to 8250,16450, 
or 16550 will enable the serial port without trying to use the FIFO. Using theUART 
type none will disablethe port. Some internal modems are billed ashavinga"16550A 
UART with alKB buffer." This is a lie. They do not really have a 16550A-compatible 
UART; instead, what they haveisa 16450-compatibleUART with a 1KB receive buffer 
to prevent receiver overruns. Thisisimportant because they do not haveatransmit 
FIFO. H ence, they are not compatible with a 16550A UART, and the autocon¬ 
figuration process will correctly identify them as 16450s. If you attempt to override this 
using theuart parameter, you seedropped characters during file transmissions. T hese 
U ART s usually have other problems: T he skip test parameter also often must be 
specified. 

When this parameter is given, setseriai asks the kernel to attempt to automatically 
configure the serial port. The I/O port must be correctly set; the kernel will attempt to 
determinetheUART type, and if the auto_irq parameter isset, Linux will attempt to 
automatically determinethe IRQ. T he autocontigure parameter should be given after 
the port, auto_irq, and skip_test parameters have been specified. 



^serial 



auto_irq 


“autoj-rq 

skip_test 


A skip_test 
baud_base baud_base 

spd_hi 

spd_vhi 

spd_cust 

spd_normal 
divisor divisor 


sak 

A sak 

fourport 
"fourport 
close_delay delay 


Session lockout 


, 'session_lockout 

pgrp_lockout 


"pgrp_lockout 

hup_notify 


A hup_notify 


During autoconfiguration, try to determine the IRQ. This feature is not guaranteed to 
always produce thecorrect result; somehardwareconfigurationswill fool theLinux 
kernel. It is generally safer not to usetheauto_irq feature but rather to specify the IRQ 
to beused explicitly, using the irq parameter. 

During autoconfiguration, do not try to determinetheIRQ. 

During autoconfiguration,skiptheUART test. Someinternal modems do not have 
N ational Semiconductor compatibleUART sbut have cheap imitations instead. Some of 
these cheesy imitation UART sdo not fully support the loopback detection mode, which 
is used by the kernel to make sure there really is a UART at a particular address before 
attempting to configure it. For certain internal modems, you will need to specify this 
parameter so Linux can initializetheUART correctly. 

During autoconfiguration, do not skip the UART test. 

This option sets the base baud rate, which is the clock frequency divided by 16. Usually, 
this value is 115200 , which is also thefastest baud rate, which the UART can support. 
Use 57.6KB when the application requests 38.4KB. This parameter can be specified by 
a non-privileged user. 

Use 115KB when the application requests 38.4KB. This parameter can be specified by a 
non-privileged user. 

Usethecustom divisor to setthespeed when theapplication requests 38.4KB. In this 
case, the baud rateisthebaud_base divided by the divisor. This parameter can be 
specified by a non-privileged user. 

Use 38.4KB when theapplication requests 38.4KB. This parameter can be specified by 
a non-privileged user. 

Thisoption sets the custom divisor. This divisor will beused when thespd_cust option 
is selected and the serial port is set to 38.4KB by theapplication. This parameter can be 
specified by a non-privileged user. 

Set the break key at the Secure Attention Key. 

D isable the Secure Attention Key. 

C onfigure the port as an AST Fourport card. 

D isable AST Fourport configuration. 

Specify the amount of time in hundredths of a second, that DTR should remain low on 
aserial line after the callout device is closed before the blocked dial-in deviceraises DTR 
again. The default value of thisoption isso, or a half-second delay. 

Lock out callout port (/dev/cuaxx) accesses across different sessions. That is, once a 
process has opened a port, do notallow a process with a different session ID to open 
that port until the first process has closed it. 

D 0 not lock out callout port accesses across different sessions. 

Lock out callout port (/dev/cuaxx) accesses across different process groups. T hat is, once 
a process has opened a port, do not allow a process in a different process group to open 
that port until the first process hasclosed it. 

D 0 not lock out callout port accesses across different process groups. 

Notify a process blocked on opening a dial-in linewhen a process has finished usinga 
callout line (either by closing it or by the serial line bei ng hung up) by returning eagain 
to the open. 

Theapplication of this parameter is for gettys that are blocked on aserial port's dial-in 
line. This allows the getty to reset the modem (which may have had its configuration 
modified by theapplication using the cal lout device) before blocking on the open again. 
Do not notify a process blocked on opening a dial-in linewhen the callout deviceis 
hung up. 
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T reat the termi os settings used by the callout device and the termi os settings used by the 
dial-in devices as separate. 

Use the same termi os structure to store both the dial-in and callout ports. This is the 
default option. 

If this particular serial port is opened as a callout device, do not hangup the tty when 
carrier detect is dropped. 

Do not skip hanging up the tty when a serial port is opened as a callout device. Of 
course, themjpcL termiosflag must be enabled if thehangup isto occur. 

CON SID ERATIO NS 0 F CONFIGU RING SERIAL PO RTS 

It is important to note that setseriai merely tells the Linux kernel where it should expect to find the I/O port and IRQ lines 
of a particular serial port. It does not configure the hardware, the actual serial board, to use a particular I/O port. To do that, 
you need to physically program the serial board, usually by setting some jumpers or by switching some DIP switches. 

This section provides some pointers in helping you decide how you want to configure your serial ports 
The"standard M S-DOS" port associations are 


/dev/ttyS0 (COM 1), port 0x3f8 IRQ 4 

/dev/ttySl (COM2), port0x2f8 IRQ 3 

/dev/ttyS2 (COM 3), port 0x3e8 IRQ 4 

/dev/ttyS 3 (COM 4), port 0x2e8 IRQ 3 


Due to the limitations in the design of the AT/ISA bus architecture, an IRQ line usually cannot be shared between two or 
more serial ports If you attempt to do this, one or both serial ports will become unreliable if you try to use both simulta¬ 
neously. This limitation can be overcome by special multiport serial port boards, which are designed to share multi pie serial 
ports over a single IRQ line. M ulti port serial cards supported by Linux include the AST FourPort, the Accent A sync board, 
the Usenet Serial II board, theBocaboard BB-1004, BB-1008, and BB-2016 boards, and the H U B-6 serial board. 

T he selection of an alternative IRQ line is difficult because most of them are already used. T he foil owing table lists the 
"standard M S-DOS" assignments of available IRQ lines: 


IRQ 3 

COM2 

IRQ 4 

COM 1 

IRQ 5 

LPT2 

IRQ 7 

LPT1 


M ost people find that IRQ 5 is a good choice assuming that there is only one parallel port active in the computer. Another 
good choice is IRQ 2 (a.k.a. IRQ 9), although this IRQ issometimes used by network cards, and very rarely will VGA cards 
be configured to use IRQ 2 as a vertical retrace interrupt. If your VGA card is configured this way, try to disable it so you 
can reclaim that I RQ linefor some other card. I t'snot necessary for Linux and most other operating systems. 

The only other available IRQ lines are 3, 4, and 7, and these are probably used by the other serial and parallel ports (Ifyour 
serial card has a 16-bit card edge connector and supports higher interrupt numbers, then IRQ 10,11,12, and 15 are also 
available.) 

On AT class machines, IRQ 2 is seen as IRQ 9, and Linux will interpret it in this manner. 

I RQ s other than 2 (9), 3,4, 5, 7,10,11,12, and 15 should not be used because they are assigned to other hardware and 
cannot, in general, be changed. H ere are the "standard" assignments 


IRQ 0 

Timer channel 0 

IRQ 1 

Keyboard 

IRQ 2 

Cascade for controller 2 

IRQ 3 

Serial port 2 

IRQ 4 

Serial port 1 


split_termios 

A split_termios 

callout_nohup 

A callout_nohup 



sets' d 



IRQ 5 

Parallel port 2 (Reserved in PS/2) 

IRQ 6 

Floppy diskette 

IRQ 7 

Parallel port 1 

IRQ 8 

Real-time clock 

IRQ 9 

Redirected to IRQ2 

IRQ 10 

Reserved 

IRQ 11 

Reserved 

IRQ 12 

Reserved (Auxiliary device in PS/2) 

IRQ 13 

M ath coprocessor 

IRQ 14 

H ard disk controller 

IRQ 15 

Reserved 


CAUTION 

Using an invalid port can lock up your machine. 

FILES 

/etc/rc.local 
/etc/rc.serial 

SEE ALSO 

tty(4), ttys(4), kernel/chr_drv/serial.c 

AUTHOR 

The original version of setseriai was written by Rick Sladkey (jrs@worid.std.com) and was modified by M ichael K. Johnson 
(johnsonm@stolaf.edu). 

This version has since been rewritten from scratch byTheodoreT s'o (tytso@mit.edu) on 1/1/93. Any bugs or problems are 
solely his responsibility. 

setseriai 2.10, 21 August 1994 


setsid 

setsid— Run a program in a new session. 

SYNOPSIS 

setsid program [ arg ... ] 

DESCRIPTION 

setsid runs a program in anew session. 

SEE ALSO 

setsid(2) 

AUTHOR 

Rick Sladkey (jrs@world.std.com) 


Linux0.99, 20 November 1993 
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showmount 

showmount— Show mount information for an N FS server. 

SYNOPSIS 

/usr/etc/showmount [\-adehv\][\--all\][\- - directories\] 

[ \ - - exports\][\- - help\] [\- - version\][\host \] 

DESCRIPTION 

showmount queries the mount daemon on a remote host for information about the state of the NFS server on that machine. 
With no options, showmount lists the set of clients who are mounting from that host. The output from showmount is designed 
to appear as though itwere processed through sort -u. 

OPTIONS 

-a or --all 
-d Or - -directories 
-e Or - -exports 
-h Or - -help 
-v Or - -version 
--no-headers 

SEE ALSO 

rpc.mountd(8), rpc.nfsd(8) 

BUGS 

The completeness and accuracy of the information that showmount displays varies according to the N FS server's implementa¬ 
tion. Because showmount sorts and uniques the output, it is impossible to determine from the output whether a client is 
mountingthesamedirectory morethan once. 

AUTHOR 

Rick Sladkey (jrs@world.std.com) 

6 October 1993 


List both the client hostnameand mounted directory in host :d r format. 
List only the di rectories mounted by some client. 

Show the N FS server's export list. 

Provide a short help summary. 

Report the current version number of the program. 

Suppress the descriptive headi ngs from the output. 


shutdown 

shutdown— Closedown the system. 

SYNOPSIS 


shutdown [ -h ; -r ] [ -fqs ] [ now } hh: ss \ +mi ns ] 

reboot [ -h | -r ] [ -fqs ] [ now j hh:ss | +mins ] 

fastboot [ -h | -r ] [ -fqs ] [ now | hh: ss [ +mi ns ] 

halt [ -h [ -r ] [ -fqs ] [ now | hh: ss j +mi ns ] 
fasthalt [ -h j -r ] [ -fqs ] [ now j hh: ss | +mi ns ] 

DESCRIPTION 

In general, shutdown prepares the system for a power down 
messages will be sent to all users warning of theshutdown. 

halt is the Same as shutdown -h -q now. 
fasthalt isthe Same as shutdown -h -q -f now. 


reboot. An absolute or delta time can be given, and periodic 





simpleinit 



reboot is the Same as shutdown -r -q now. 
fastboot isthe Same as shutdown -r -q -f now. 

The default delta time if none is specified, istwo minutes. 

Five minutes before shutdown (or immediately, if shutdown is less than five minutes away), the /etc/noiogin file is created 
with a message stating that the system is going down and that logins are no longer permitted. The iogin(l) program will not 
allow non-superusers to log in during this period. A message will be sent to all users at this time 

When theshutdown time arrives, shutdown notifies all users, tel Is ±nit(8) not to spawn moregetty(8)s, writes the shutdown 
time into the /var/iog/wtmp file kills all other processes on the system, sync(2)s unmounts all the disks, sync(2)s again, waits 
for a second, and then either terminates or reboots the system. 

OPTIONS 

-h 
-r 
-f 

•q 

•s 

FILES 

/etc/rc 
/fastboot 
/etc/singleboot 
/etc/nologin 
/var/log/wtmp 

SEE ALSO 

umount(8), login(l), reboot(2), simpleinit(8), init(8) 

BUGS 

Unlike theBSD shutdown, users are notified of shutdown only once or twice, instead of manytimes, and at shorter and 
shorter intervals as "apocalypse approaches." 

AUTHOR 

poe@daimi.aau.dk. M Odified by jrs@world.std.com. 

Linux0.99, 20 November 1993 


H alt the system. D o not reboot. This option is used when powering down the system. 
Reboot the system. 

Fast. When the system is rebooted, the filesystems will not be checked. This is arranged 
by creating /fastboot, which /etc/rc must detect (and delete). 

Q uiet. This uses a default broadcast message and does not prompt the user for one. 
Reboot in single-user mode. This is arranged by creating /etc/singieboot, which 
simpieinit(8) detects (and deletes). 


simpleinit 

simpleinit— Process control initialization. 

SYNOPSIS 


init [ single ] 
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DESCRIPTION 

init is invoked as the last step in the Linux boot sequence If the single option is used, or if the file /etc/singieboot exists, 
then singleuser mode will be entered, by starting /bin/sh. If thefile /etc/securesingie exists, then the root password will be 
required to start singleuser mode. If the root password does not exist, or if /etc/passwd does not exist, the checking of the 
password will be skipped. 

If thefile /etc/Tz exists, then the contents of that file will be read and used to set the tz environment variable for each 
process started by simpieinit. This "feature" is only available if it's configured at compile time. It's not usually needed. 

After single-user mode is terminated, the /etc/rc file is executed, and the information in /etc/inittab will be used to start 
processes. 

W hile init isrunning, several signals are trapped with special action taken. Because init hasPID 1, sending signals to the 
init process is easy with the kiii(l) command. 

If init catches a sighup (hangup) signal, the /etc/inittab will be read again. If init catches a sigtstp (terminal stop) signal, 
no more processes will be spawned. This is a toggle, which is reset if init catches another sigtstp signal. 

If init catches a sigint (interrupt) signal, init will sync a few times and try to start reboot. Failing this init will execute the 
system reboot(2) call. Under Linux, it ispossibleto configure theCtrl-FAIt+D el sequence to send a signal to init instead of 
rebooting the system. 

THE inittab FILE 

Because of the number of init programs that are appearing in the Linux community, the documentation for the 
/etc/inittab file which is usually found with the inittab(5) man page, is presented here: 

The format is 

ttyline:termcap- entry:getty- command 

An example follows: 

tty 1 :console:/sbin/getty 9600 tty 1 
tty2:console:/sbin/getty 9600 tty2 
tty3:console:/sbin/getty 9600 tty3 
tty4:console:/sbin/getty 9600 tty4 

# tty5:console:/sbin/getty 9600 tty5 

# ttySI:dumb:/sbin/getty 9600 ttySI 

# ttyS2:dumb:/sbin/getty -m -t60 2400 ttyS2 

Lines beginning with the # character are treated as comments. Please see documentation for the getty(8) command that you 
are using because there are several of these in the Linux community at this time 

FILES 

/etc/inittab 

/etc/singleboot 

/etc/securesingle 

/etc/TZ 

/etc/passwd 

/etc/rc 

SEE ALSO 

inittab(5), ctrlaltdel(8) reboot(8), termcap(5), getty(8), agetty(8), shutdown(8) 



sliplogin 



BUGS 

This program is cal led simpieinit to distinguish it from the System V compatible versions of init that are starting to appear 
in the Linux community, simpieinit should be linked to, or made identical with, init for correct functionality. 

AUTHOR 

Peter Orbaek (poe@daimi.aau.dk), version 1.20, with patches for single-user mode by Werner Almesberger. 

Linux0.99, 20 November 1993 


slattach 

siattach— Attach a network interface to a serial line. 

SYNOPSIS 

slattach [- v ] [-p proto] [-s speed] [tty] 

DESCRIPTION 

slattach is a I ittle program that can be used to put a normal terminal ("serial'') line into oneof several "network" modes, 
thus allowing you to use it for point-to-point links to other computers. 

OPTIONS 

[-V] 

[-p proto] 

[-s speed] 

FILES 

/dev/cua* 

BUGS 

N one so far. 

AUTHOR 

Fred N . van Kempen (waitje@uwalt.nl.mugnet.org) 

20 September 1993 


Enable debugging output. U seful when determining why a given setup doesn't work. 

Set a specific kind of protocol to use on the line. The default is set to csiip, compressed 
SLIP. Other possible values are slip (normal SLIP), ppp (Point-to-Point Protocol), and 
kiss (AX.25TNC protocol). 

Set a specific line speed other than the default. 

If no arguments are given, the current terminal line (usually the login device) isused. 
Otherwise, an attempt ismadeto claim theindicated terminal port, lock it, and open it. 


sliplogin 

sliplogin— Attach a serial line network interface. 

SYNOPSIS 

sliplogin [I ogi nname ] 

DESCRIPTION 

sliplogin is used to turn the terminal line on standard input into a serial line IP SLIP link to a remote host. To do this the 
program searches the file for an entry matching i ogi nname (which defaults to the current login name if omitted). If a 
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matching entry is found, the line is configured appropriately for slip (8-bit transparent I/O) and converted to slip line 
discipline Then a shell script is invoked to initialize the slip interface with the appropriate local and remote IP address, 
netmask, and so on. 

The usual initialization script is /etc/slip/slip. igin, but if particular hosts need special initialization, the file 
/etc/slip/slip.login.loginname will be executed instead if it exists. T he script is invoked with the parameters 

siipunit The unit number of the slip interface assigned to this line, such as 0 for sio. 

speed The speed of the line. 

args T he arguments from the entry, in order starting with 1 ogi nname. 

Only the superuser can attach a network interface. The interface is automatically detached when the other end hangs up or 
the siipiogin process dies. If the kernel slip module has been configured for it, all routes through that interface will also 
disappear at the same time. If there is other processing a site wants done upon hangup, the file /etc/slip/slip, logout or 
/etc/siip/siip. logout, loginname is executed if it exists. It is given the same arguments as the login script. 

FORMATOF/etc/Slip. hosts 

Comments (lines starting with a#) and blank lines are ignored. Other lines must start with ai ogi nname, but the remaining 
arguments can be whatever isappropriateforthefilethatwill be executed for that name. Arguments are separated by 
whitespace and follow normal sh(l) quoting conventions (however, 1 ogi nname cannot be quoted). Usually, lineshavethe 
form I ogi n n a me local-address remote-address netmask opt-args. local-address and remote-address are the IP hostnames Or 
addresses of the local and remote endsof theslip line, and netmask is the appropriate IP netmask. These arguments are passed 
directly to ifconfig(8). opt-args are optional arguments used to configure the line. 

EXAMPLE 

Thenormal use of siipiogin isto create a entry for each legal, remote si ip site with siipiogin as the shell forthat entry, 
such as 

Sfoo:ikhuy6:2010:1:slip line to too:/tmp:/usr/sbin/sliplogin. 

(Our convention isto name the account used by remote host hostname as shostname.) Then an entry is added that looks I ike 
Sfoo 'hostname' foo netmask 

'hostname 1 will be evaluated by sh to the local hostname and netmask is the local host IP netmask. 

N otethat siipiogin must besetuid to root, and although it's not a security hole moral defectives can use it to place terminal 
lines in an unusable state or deny access to legitimate users of a remote slip line. To prevent this, a site can create a group, say 
slip, that only theslip login accounts are put in and then make sure that /sbin/siipiogin is in group slip and mode 4550 
(setuid root, only group slip can execute binary). 

DIAGNOSTICS 

siipiogin logs various information to the system log daemon, sysiogd(8), with a facility code of daemon. The messages are 
listed here, grouped by severity level. 


Error Se/erity 

ioctl (TCGETS): reason 
ioctl (TCSETS): reason 
/etc/slip.hosts: reason 
access denied for user 


A tcgets ioctl to get the line parameters failed. 

A tcsets ioctl to set the line parameters failed. 
Thefilecould not beopened. 

N 0 entry for user was found in /etc/siip/siip. hosts 


Notice Se/erity 


"attaching slip unit" unit for 
I 0 g i n n a me SLIP unit 


Unit was successful ly attached. 



sync 

SEE ALSO 

slattach(8), syslogd(8) 

HISTORY 

T he siipiogin command is currently in beta test. 

5 August 1991 

swapon, swapoff 

swapon, swapoff — Enabl^disable devices and files for paging and swapping. 

SYNOPSIS 

/sbin/swapon -a 
/sbin/swapon s p e cia IfiIe ... 

/sbin/swapoff -a 
/sbin/swapoff specialfile ... 

DESCRIPTION 

swapon is used to specify devi ces on which paging and swapping are to take place. Calls to swapon usually occur in the system 
multiuser initialization file /etc/rc making all swap devices available, so that the paging and swapping activity is interleaved 
across several devicesand files. 

Usually, thefirstform isused: 

-a All devices marked assw swap devices in /etc/fstab are made available. 

swapoff disables swapping on the specified devicesand files or on all swap entries in /etc/fstab when the -a flag is given. 

SEE ALSO 

swapon(2), swapoff(2), fstab(5), init(8), mkswap(8), rc(8), mount(8) 

FILES 

/dev/hd[ab] ? Standard paging devices 

/dev/sd[ab] ? Standard (SCSI) paging devices 

/etc/fstab ASCII filesystem description table 

HISTORY 

The swapon command appeared in 4.0 BSD. 

AUTHORS 

See the Linux mount(8) man page for a complete author list. Primary contributors include Doug Quale, H.J. Lu, Rick 
Sladkey, and Stephen T weedie. 

Linux0.99, 21November 1993 

sync 

sync— Flush Linux filesystem buffers. 

SYNOPSIS 



sync 
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DESCRIPTION 

sync executes sync(2), which flushes the filesystem buffers to disk, sync should be called before the processor is halted in an 
unusual manner (before causing a kernel panic when debugging new kernel code). In general, the processor should be halted 
using the reboot(8) or hait(8) commands, which attempt to put the system in a quiescent state before calling sync(2). 

From Linus: "N otethat sync is only guaranteed to schedule the dirty blocks for writing: It can actually take a short time 
before all the blocks are finally written. If you are doing the sync with the expectation of killing the machinesoon after, 
please take this into account and sleep for a few seconds. (Thereboot(8) command takes these precautions.)'' 

SEE ALSO 

sync(2), update(8), reboot(8), halt(8) 

AUTHOR 

LinusT orvalds (tonvalds@cs.helsinki.fi) 

Linux0.99, 20 November 1993 


sysklogd 

syskiogd— Linux system logging utilities. 

DESCRIPTION 

syskiogd provides two system utilities, which provide support for system logging and kernel message trapping. Support of 
both inetd and U NIX domain sockets enables this utility package to support both local and remote logging. 

System logging is provided by a version of sysiogd derived from the stock BSD sources. Support for kernel logging is 
provided bythekiogd utility, which allows kernel logging to be conducted in either a stand-alone fashion or asaclient of 
sysiogd. 

Although the sysiogd sources have been heavily modified, a couple of notes are in order. First of all, there has been a 
systematic attempt to ensure that sysiogd follows standard BSD behavior as its default. The second important concept to 
note is that this version of sysiogd interacts transparently with the version of sysiog found in the standard libraries. If a 
binary linked to the standard shared libraries fails to function correctly, we want an example of the anomalous behavior. 

CONFIGURATION FILE SYNTAX DIFFERENCES 

sysiogd uses a slightly different syntax for its configuration file from that of the original BSD sources. Originally, all messages 
of a specific priority and above were forwarded to the log fi le. 

For example, the following line caused all output from the daemon facilities to go into /usr/adm/daemons: 

# Sample sysiog.conf 
daemon.debug /usr/adm/daemons 

Under the new scheme, this behavior remains the same. The difference isthe addition of two new wildcard specifiers: 
the asterisk (*) and the equals sign (=). The* specifies that all messages for the indicated facility are to be directed to the 
destination. N otethat this behavior is degenerate with specifying a priority level of debug. Users have indicated that the 
asterisk notation is more intuitive. 

T he = wildcard is used to restrict logging to the specified priority class. This allows, for example, routing only debug messages 
to a particular logging source. 

For example, the following line in sysiog. conf directs debug messages from all sources to the /usr/adm/debug file 

# Sample sysiog.conf 
daemon.=debug /usr/adm/debug 



s/sktogd 



This may take some acclimatization for those individuals used to the pure BSD behavior, but testers have indicated that this 
syntax is somewhat more flexible than the BSD behavior. N ote that these changes should not affect standard sysiog.conf 
files. You must specifically modify theconfiguration files to obtain the enhanced behavior. 

SUPPORT FOR REMOTE LOGGING 

These modifications provide network support to thesysiogd facility. N etwork support means that messages can be forwarded 
from one node running sysiogd to another node running sysiogd where they will be actually logged to a disk file. 

The strategy is to have sysiogd listen on aU NIX domain socket for locally generated log messages. This behavior will allow 
sysiogd to interoperate with thesysiog found in the standard C library. Atthesametime sysiogd listens on thestandard 
sysiog port for messages forwarded from other hosts. T o have this work correctly, the services files (typically found in 
/usr/etc/inet) must have the following entry: 

sysiog 514/udp 

T o cause messages to be forwarded to another host, replace the normal filelinein thesysiog.conf file with thenameof the 
host to which the messages is to be sent prepended with an @. 

For example, to forward all messages to a remote host, use the following sysiog.conf entry: 

# Sample sysiogd configuration file to 

# messages to a remote host forward all. 

.* @hostname 

T o forward all kernel messages to a remote host, theconfiguration file is 

# Sample configuration file to forward all kernel 

# messages to a remote host, 
kern.* @hostname 

OUTPUTTO NAMED PIPES (FIFOS) 

This version of sysiogd has support for logging output to named pipes (FIFOs). A FIFO or named pipe can beused asa 
destination for log messages by prepending a | to thenameof the file. This is handy for debugging. N ote that the FIFO must 
be created with themkfifo command before sysiogd is started. 

The following configuration file routes debug messages from the kernel to a FIFO: 

# Sample configuration to route kernel debugging 

# messages ONLY to /usr/adm/debug which is a 

# named pipe. 

kern.=debug |/usr/adm/debug 

INSTALLATION CONCERNS 

There is probably one important consideration when installing this version of sysiogd. This version of sysiogd is dependent 
on proper formatting of messages by thesysiog function. Thefunctioning of thesysiog function in the shared libraries 
changed somewhere in the region of iibc.so.4. [2-4] .n. The specific change was to null-terminate the message before 
transmitting it to the / dev/iog socket. Proper functioning of this version of sysiogd is dependent on null-termination of the 
message. 

This problem will typically manifest itself if old statically linked binaries are being used on the system. Binaries using old 
versions of thesysiog function will cause empty lines to be logged, followed by the message with the first character in the 
message removed. Relinking these binaries to newer versions of the shared libraries will correct this problem. 

SECURITY THREATS 

There is the potential for thesysiogd daemon to beused asa conduit for a denial of service attack. Thanks go to John 
M orrison (jmorriso@mab.ee. ubc.ca) for alerting me to this potential. A rogue programmer could very easily flood the 
sysiogd daemon with sysiog messages resulting in the log files consuming all the remaining space on the filesystem. 
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Activating logging over the met domain sockets will of course expose a system to risks outside of programs or individuals on 
the local machine. 

Version 1.2 of the utility set will address this problem. In the meantime, there are a number of methods for protecting a 
machine: 

1. Logging can bedirected to an isolated or non-root filesystem, which, if filled, will not impairthe machine. 

2. T he ext 2 filesystem can be used, which can be configured to limit a certain percentage of a filesystem to usage by root 
only. N ote that this will require sysiogd to be run as a non-root process. Also note that this will prevent usage of remote 
logging because sysiogd will be unable to bind to the 514/U D P socket. 

3. D isabling met domain sockets will limitrisk to thelocal machine. 

4. Use Step 3 and if the problem persists and is not secondary to a rogue program or daemon, get a 3.5 foot (approximately 
1 meter) length of sucker rod and have a chat with the user in question. A sucker rod is3/4-, 7/8-, or 1-inch hardened 
steel rod, malethreaded on each end. Its primary use i n the oil industry in Western N orth Dakota and other locationsis 
to pump-suck oil from oil wells. Secondary uses are for the construction of cattle feed lots and for dealing with the 
occasional recalcitrant or belligerent individual. 

FILES 

/etc/syslog.conf 

BUGS 

Primarily, security concerns will be addressed in version 1.2. 

SEE ALSO 

klogd(l) 

COLLABORATORS 

D r. G reg W ettstein (greg%wind.uucp@plains.nodak.edu) 

Enjellic Systems D evelopment 

Oncology Research Division Computing Facility 

Roger M aris C ancer C enter 

Fargo, N D 

Stephen T weedie 

D epartment of C omputer Science 

Edinburgh University, Scotland 

J uha V irtanen 

(jiivee@hut.fi) 

ShaneAlderton 
(shane@scs.apana.org.au) 

Version 1.1, 28January 1994 


sysiogd 

sysiogd— Log systems messages. 

SYNOPSIS 

sysiogd [-f config_fiI e] [-m marki nterval ] [-p I ogsocket ] 

DESCRIPTION 

sysiogd reads and logs messages to the system console, log files, and other machines or users as specified by its configuration 
file. The options are as follows: 
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-f Specify the pathname of an alternate configuration file; the default is/etc/sysiog.cont. 

-m Select the number of minutes between "mark" messages; the default is 20 minutes. 

-p Specify the pathname of an alternate log socket; the default is /dev/iog. 

sysiogd reads its configuration file when it starts up and whenever it receives a hangup signal. For information on theformat 
of theconfiguration file seesysiog.conf(5). 

sysiogd reads messages from theU N IX domain socket /dev/iog, from an Internet domain socket specified in /etc/services, 
and from the special device /dev/kiog (to read kernel messages). 

sysiogd creates the file /var/run/sysiog.pid and stores its process ID there. This can be used to kill or reconfigure sysiogd. 

The message sent to sysiogd should consist of a single line. The message can contain a priority code, which should be a 
preceding decimal number in angle braces, such as<5>. This priority code should map into the priorities defined in the 
include file <sys/syslog ,h>. 

FILES 

/etc/syslog.conf 
/var/run/syslog.pid 
/dev/log 
/dev/klog 

SEE ALSO 

logger(l), syslog(3), services(5), syslog.conf(5) 

HISTORY 

The sysiogd command appeared in BSD 4.3. 

BSD 4.2,16 March 1991 


Theconfiguration file 

The process ID of current sysiogd 

N ameof theU N IX domain datagram log socket 

The kernel log device 


talkd 

taikd— Remote user communication server. 

SYNOPSIS 

talkd 

DESCRIPTION 

taikd is the server that notifies a user that someone else wants to initiate a conversation. It acts a repository of invitations, 
responding to requests by clients who wantto rendezvousto hold a conversation. In normal operation, a client, the caller, 
initiates a rendezvous by sending a ctl msg to the server of type look up (see protocols/taikd. h). This causes the server to 
search its invitation tables to check if an invitation currently exists for the caller (to speak to the cal lee specified in the 
message). If the lookup fails, the caller then sends an announce message, causing the server to broadcast an announcement on 
the cal lee's login ports requesting contact. When the callee responds, the local server uses the recorded invitation to respond 
with the appropriate rendezvous address and the caller and callee client programs establish a stream connection through 
which the conversation takes place. 

SEE ALSO 

talk(l), write(l) 
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HISTORY 

Thetaikd command appeared in BSD 4.3. 


BSD 4.3,16 March 1991 


telnetd 

teinetd— DARPA Telnet protocol server. 

SYNOPSIS 

/etc/telnetd [-debug [port]] [-1][-D opt i ons ][-D report ] 

[-D exerci se][-D netdata ] [-D ptydata] 

DESCRIPTION 

teinetd is a server that supports the DARPA standard T el net virtual terminal protocol, teinetd is invoked by the Internet 
server (see inetd(8)), usually for requests to connect to theTelnet port as indicated by the /etc/services file (see 
services(5)). If desired the -debug can be used, to startup teinetd manually, instead of through inetd(8). If started up this 
way, port may be specified to run teinetd on an alternate TCP port number. 

The -d option can be used for debugging purposes. This allows T elnet to print debugging information to the connection, 
allowing the user to see what teinetd is doing. There are several modifiers: opt i ons prints information about the negotiation 
of Telnet options, report prints theoptionsinformation, plus some additional information about what processing isgoing 
on, netdata displays the data stream received by teinetd, ptydata displays data written to the pty, and exercise has not been 
implemented yet. 

teinetd operates by allocating a pseudo-terminal device (see pty(4)) for a client) and then creating a login process that has the 
slave side of the pseudo-terminal asstdm, stdout, and stderr. teinetd manipulates the master side of the pseudo-terminal, 
implementing theT elnet protocol and passing characters between the remote client and the login process. 

When a Tel net session is started, teinetd sendsT elnet options to the client side, indicating a willingness to do a remote echo 
Of characters, to suppress go ahead, to do remote flow control, and to receive terminal type information, terminal Speed 
information, and window size information from the remote client. If the remote client is willing, the remote terminal type is 
propagated in the environment of the created login process. The pseudo-terminal allocated to the client is configured to 
operate in cooked mode and with xtabs and crmod enabled (see tty(4)). 

teinetd iswilling to do echo, binary, suppress go ahead, and timing mark, teinetd i S Wi lling to have the remote Client 
do linemode, binary, terminal type, terminal speed, window size, toggle flow control, environment,X display location, and 
suppress go ahead. 

If the file /etc /issue, net is present, teinetd will show its contents before the login prompt of a Telnet session (see 
issue.net(5)). 

SEE ALSO 

telnet(l), issue.net(5) 

BUGS 

SomeT elnet commands are only partially implemented. 

Because of bugs in the original 4.2 BSD teinet(l), teinetd performs some dubious protocol exchanges to try to discover if 
the remote client is, in fact, a4.2 BSD teinet(l). 

Binary mode has no common interpretation except between similar operating systems (U NIX, in this case). 
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The terminal type name received from the remote client is converted to lowercase, teinetd never sendsT el net go ahead 
commands. 

20 April 1991 


tftpd 

tftpd — D ARPA Trivial FileTransfer Protocol server. 

SYNOPSIS 

tftpd [directory ...] 

DESCRIPTION 

tftpd is a server that supports the D ARPA Trivial FileT ransfer Protocol. TheT FTP server operates at the port indicated in 
thetftp service description; see services(5). The server is usually started by inetd(8). 

Theuseof tftp(l) does not require an account or password on the remote system. Due to thelack of authentication 
information, tftpd will allow only publicly readable files to be accessed. Files may be written only if they already exist and are 
publicly writable N ote that this extends the concept of publicto includeall userson all hosts that can be reached through 
the network; this may not be appropriate on all systems, and its implications should be considered before enabling thetftp 
service. The server should havetheuser ID with thelowest possible privilege. 

SEE ALSO 

tftp(l), inetd(8) 

HISTORY 

Thetftpd command appeared in BSD 4.2. 

BSD 4.2,13 May 1991 


timed 

timed— T i me server daemon. 

SYNOPSIS 

timed [-M] [-t] [-d] [-i network] [-n network] [-F hostl h o s 12 ...] 

DESCRIPTION 

timed is a time server daemon and is usually invoked at boot time from the rc(8) file. It synchronizes the host's time with the 
time of other machines in a local area network running timed(8). These time servers will slow down the clocks of some 
machines and speed up the clocks of others to bring them to the average network time. The average network time is 
computed from measurements of clock differences using the 1C M P timestamp request message. 

The service provided by timed is based on a master-slave scheme. When timed(8) is started on a machine it asks the master 
for the network time and sets the host's clock to that time. After that, it accepts synchronization messages periodically sent by 
the master and calls adjtime(2) to perform the needed correctionson the host's clock. 

It also communicates with date(l) to set the date globally and with timedc(8), a timed control program. If the machine 
running the master crashes, then the slaves elect a new master from among slaves running with the -m flag. A timed running 
without the -m or -f flags remains a slave. The -t flag enables timed to trace the messages it receives in the file 
/var/iog/timed.iog. T racing can be turned on or off by the program timedc(8). The -d flag is for debugging the daemon. 

It causes the program to not put itself into the background. Usually, timed checks for a master timeserver on each network 
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to which it is connected, except as modified by the options. It requests synchronization service from the first master server 
located. If permitted by the -m flag, it provides synchronization service on any attached networks on which no current master 
server is detected. Such a server propagates the time computed by the top-level master. The -n flag, followed by the name of 
a network that the host isconnected to (seenetworks(5)), overrides the default choice of the network addresses made by the 
program. Each time the -n flag appears, that network name is added to a list of valid networks. All other networks are 
ignored. The -i flag, followed by the name of a network to which the host isconnected (seenetworks(5)), overrides the 
default choice of the network addresses made by the program. Each time the -i flag appears, that network name is added to a 
list of networks to ignore. All other networks are used by the time daemon. The -n and -i flags are meaningless if used 
together. 

timed checks for a master timeserver on each network to which it isconnected, except as modified by the -n and -i options. 

If it finds masters on more than one network, it chooses one network on which to be a "slave'' and then periodically checks 
the other networks to see if the masters there have disappeared. 

Oneway to synchronize a group of machines is to use an NT P daemon to synchronize the clock of one machine to a distant 
standard or a radio receiver and -F hostnameto tell itstimed daemon to trust only itself. 

M essages printed by the kernel on the system console occur with interrupts disabled. This means that the clock stops whi le 
they are printing. A machine with many disk or network hardware problems and consequent messages cannot keep good 
time by itself. Each message typically causes the clock to lose a dozen milliseconds. A time daemon can correct the result. 

M essages in the system log about machines that failed to respond usually indicate machines that crashed or were turned off. 
Complaints about machines that failed to respond to initial time settings are often associated with "multi-homed'' machines 
that looked for time masters on more than one network and eventually chose to become a slave on the other network. 

WARNING 

If two or more time daemons, whether timed, N TP, try to adjust the same clock, temporal chaos will result. If both this and 
another time daemon are run on the same machine, ensure that the -f flag is used, so that timed never attempts to adjust the 
local clock. 

The protocol is based on U D P/IP broadcasts. All machines within the range of a broadcast that are using theTSP protocol 
must cooperate. There cannot be more than a single administrative domain using the -f flag among all machines reached by 
a broadcast packet. Failure to follow this rule is usually indicated by complaints concerning "untrusted" machines in the 
system log. 

FILES 

/var/iog/timed.iog tracing file for timed 
/var/log/timed.masterlog log filefor master timed 

SEE ALSO 

date(l), adjtime(2), gettimeofday(2), icmp(4), timedc(8), "TSP: T heT i me Synchronization Protocol for U NIX 4.3 BSD," 

R. Gusella, S. Zatti. 

HISTORY 

The timed daemon appeared in BSD 4.3. 

BSD 4.3,11 May 1993 


timedc 

timedc— Timed control program. 

SYNOPSIS 

timedc [command] [argument ...] 
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DESCRIPTION 

timedc is used to control theoperation of thetimed(8) program. It may be used to 
M easure the differences between machines' clocks 
Find the location where the master time server is running 
Enable or disable tracing of messages received by timed 
Perform various debugging actions 

Without any arguments, timedc will prompt for commands from the standard input. If arguments are supplied, timedc 
interprets the first argument as a command and the remaining arguments as parameters to the command. T he standard input 
may be redirected, causing timedc to read commandsfrom afile Commands may be abbreviated; recognized commands are 

? [command ...] 
help [command ...] 

clockdiff host ... 

msite [host ...] 
trace {on J off} 
election host 

quit Exit from timedc 

Other commands may be included for use in testing and debugging timed; the help command and the program source may 
be consulted for details. 

FILES 

/var/iog/timed.iog tracing file for timed 
/var/log/timed.masterlog log filefor master timed 

SEE ALSO 

date(l), adjtime(2), icmp(4), timed(8), "TSP: The Time Synchronization Protocol for U NIX 4.3 BSD," R. Gusella, S. Zatti. 

DIAGNOSTICS 

?Ambiguous command Abbreviation matches more than onecommand 

?Invalid command No match found 

?priviieged command C ommand can be executed by root only 


Print a short description of each command specified in the argument list or, if no 
arguments are given, a list of the recognized commands. 

Compute the differences between the clock of the host machine and the clocks of the 

machines given as arguments 

Show the master time server for specified hosts. 

E nable or di sable the traci ng of i ncomi ng messages to timed in thefi le. 
Asksthedaemon on th e target host to reset its "election” timers and to ensure that a 
time master has been elected. 


HISTORY 

The timedc command appeared in BSD 4.3. 


BSD 4.3,11 May 1993 


traceroute 

traceroute— Print the route that packets take to the network host. 

SYNOPSIS 


traceroute [-m ma x _ 111 ] [ - n ] [-p port] [-q nqueries] 

[-r] [ - s srcaddr ] [-t tos] [-w waittime] host [packetsize] 
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DESCRIPTION 

The Internet is a large and complex aggregation of network hardware, connected together by gateways. T racking the route 
one's packets follow (or finding the miscreant gateway that's discarding your packets) can be difficult, traceroute utilizes the 
IP protocol ti me-to-live field and attempts to elicit an icmp time_exceeded response from each gateway along the path to 
some host. 


The only mandatory parameter is the destination hostname or IP number. The default probe datagram length is 38 bytes, 
butthiscan be increased by specifying a packet size (in bytes) after the destination hostname. 

Other options are 


- m ma x 111 


-p port 


-q nqueri es 
-r 


-s src addr 


•t tos 


Set the max ti me-to-live (max number of hops) used in outgoing probe packets. The 
default is 30 hops (the same default used forTCP connections). 

Print hop addresses numerically rather than symbolically and numerically (saves a 
nameserver address-to-name lookup for each gateway found on the path). 

Set the base U D P port number used in probes (default is 33434 ). traceroute hopes that 
nothing is listening on U D P ports base to base + nhops-1 at the destination host (so an 
icmp portjjnreachable message will be returned to terminate the route tracing). If 
something is listening on a port in the default range, this option can be used to pick an 
unused port range. 

Set the number of probes per tti to nquer i es (default is three probes). 

Bypass the normal routing tables and send directly to a host on an attached network. If 
the host is not on a directly attached network, an error is returned. This option can be 
used to ping a local host through an interface that has no route through it (for example, 
after the interface was dropped by routed(8)). 

Use the following IP address (which must be given as an IP number, not a hostname) as 
the source address in outgoing probe packets. On hosts with more than one IP address, 
this option can be used to force the source address to be something other than the IP 
address of the interface the probe packet is sent on. If the IP address is not one of this 
machine's interface ad dresses, an error is returned and nothing is sent. 

Set the type-of-service in probe packets to the following value (default zero). T he value 
must be a decimal integer in the range 0 to 255 . This option can be used to see if 
different types of service result in different paths. (If you are not running a BSD 4.3 
tahoeor later system, this may be academic because the normal network services such as 
T elnet and FTP don’t let you control theTOS). N ot all values of TOS are legal or 
meaningful; seethelP spec for definitions Useful values are probably (low delay) and 
(high throughput). 

V erbose output. Received ICMP packets other than time_exceeded and uNREACHABLEsare 
listed. 

Set the time (in seconds) to wait for a response to a probe (default is 3 seconds). 


This program attempts to trace the route an IP packet would follow to some Internet host by launching U D P probe packets 
with a small tti (time to live) and then listening for an ICMP "time exceeded" reply from agateway. We start our probes 
with a tti of one and increase by one until we get an ICM P "port unreachable” (which meanswegotto "host”) or hit a max 
(which defaults to 30 hops and can be changed with the -m flag). Three probes (changed with the -q flag) are sent at each tti 
setting and a line is printed showing the tti, address of the gateway, and round-trip time of each probe. If the probe answers 
come from different gateways, the address of each responding system will be printed. If there is no response within a three 
second time-out interval (changed with the -w flag), a * is printed for that probe. 

We don't want the destination host to process the U D P probe packets, so the destination port is set to an unlikely value (if 
some clod on the destination isusingthat value, it can be changed with the -p flag). 
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A sample use and output might be 

[yak 71]% traceroute nis.nsf.net. 

traceroute to nis.nsf.net (35.1.1.48), 30 hops max, 

56 byte packet 

1 helios.ee.lbl.gov (128.3.112.1) 19 ms 19 ms 0 ms 

2 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 39 ms 19 ms 

3 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 39 ms 19 ms 

4 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 39 ms 40 ms 39 ms 

5 ccn-nerif22.Berkeley.EDU (128.32.168.22) 39 ms 39 ms 39 ms 

6 128.32.197.4 (128.32.197.4) 40 ms 59 ms 59 ms 

7 131.119.2.5(131.119.2.5) 59ms 59ms 59ms 

8 129.140.70.13 (129.140.70.13) 99 ms 99 ms 80 ms 

9 129.140.71.6(129.140.71.6) 139ms 239ms 319ms 

10 129.140.81.7(129.140.81.7) 220ms 199 ms 199ms 

11 nic.merit.edu (35.1.1.48) 239 ms 239 ms 239 ms 

N otethat Lines 2 and 3 are the same. This is due to a buggy kernel on the second hop system— ibi-csam.arpa— that 
forwards packets with a zero tti (a bug in the distributed version of 4.3 BSD). N otethat you have to guess what path the 
packets are taking cross-country because the N SFN et ( 129 . 140 ) doesn't supply address-to-name translations for its N SSs. 

A more interesting example is 

[yak 72]% traceroute allspice.lcs.mit.edu. 

traceroute to allspice.lcs.mit.edu (18.26.0.115), 30 hops max 

1 helios.ee.lbl.gov (128.3.112.1) 0 ms 0 ms 0 ms 

2 lilac-dmc.Berkeley.EDU (128.32.216.1) 19 ms 19 ms 19 ms 

3 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 19 ms 19 ms 

4 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 19 ms 39 ms 39 ms 

5 ccn-nerif22.Berkeley.EDU (128.32.168.22) 20 ms 39 ms 39 ms 

6 128.32.197.4 (128.32.197.4) 59 ms 119 ms 39 ms 

7 131.119.2.5(131.119.2.5) 59ms 59ms 39ms 

8 129.140.70.13 (129.140.70.13) 80 ms 79 ms 99 ms 

9 129.140.71.6(129.140.71.6) 139ms 139ms 159ms 

10 129.140.81.7(129.140.81.7) 199 ms 180ms 300ms 

11 129.140.72.17 (129.140.72.17) 300 ms 239 ms 239 ms 

12 * * * 

13 128.121.54.72(128.121.54.72) 259ms 499ms 279ms 

14 * * * 

15 * * * 

16 * * * 

17 * * * 

18 ALLSPICE.LCS.MIT.EDU (18.26.0.115) 339 ms 279 ms 279 ms 

N otethat the gateways 12,14,15,16, and 17 hop away. Either don't send ICMP "time exceeded" messages or send them 
with a tti too small to reach us. Lines 14-17 are running the M IT C Gateway code that doesn't send "timeexceeded"s. God 
only knows what's going on with 12. 

The si lent gateway 12 may be the result of a bug in the 4.[23] BSD network code (and its derivatives): 4.x (x <=3) sends an 
unreachable message using whatever tti remainsin theoriginal datagram. Because for gateways the remaining tti iszero, the 
ICMP "time exceeded" is guaranteed to not make it back to us. The behavior of this bug is slightly more interesting when it 
appears on thedestination system: 

1 helios.ee.lbl.gov (128.3.112.1) 0 ms 0 ms 0 ms 

2 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 19 ms 39 ms 

3 lilac-dmc.Berkeley.EDU (128.32.216.1) 19 ms 39 ms 19 ms 

4 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 39 ms 40 ms 19 ms 

5 ccn-nerif35.Berkeley.EDU (128.32.168.35) 39 ms 39 ms 39 ms 

6 csgw.Berkeley.EDU (128.32.133.254) 39 ms 59 ms 39 ms 

7 *** 

8 *** 
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9 *** 

10 * * * 

11 * * * 

12 * * * 

13 rip.Berkeley.EDU (128.32.131.22) 59 ms ! 39 ms ! 39 ms 

l 

N otice that there are 12 "gateways" (13 is the final destination) and exactly the last half of them are "missing." What's really 
happening is that rip (a Sun-3 running Sun OS3.5) is using them from our arriving datagram as them in its 1C M P reply. 
The reply will timeout on the return path (with no notice sent to anyone because 1C M Ps aren't sent for 1C M Ps) until we 
probe with a tti that's at least twice the path length. That is, rip is really only seven hops away. A reply that returns with a 
tti of i is a clue this problem exists, traceroute prints a \ after the time if the tti is less than or equal to 1. Because vendors 
ship a lot of obsolete (D EC Ultrix, Sun 3.x) or non-standard H PUX software, expect to see this problem frequently or take 
care pi ckingthe target host of your probes. Other possi ble annotations after thetime are m, in, ip (gota host, network, or 
protocol unreachable), is, or if (source route failed or fragmentation needed— neither of these should ever occur and the 
associated gateway is busted if you see one). If almost all the probes result in some kind of unreachable, traceroute will give 
up and exit. 

Thisprogram is intended forusein network testing, measurement, and management. 11 should beused primarily for manual 
fault isolation. Because of the load it could impose on the network, it is unwise to use traceroute during normal operations 
or from automated scripts 

AUTHOR 

Implemented by Van Jacobson from a suggestion by Steve Deering. Debugged by a cast of thousands with particularly 
cogent suggestions or fixes from C. Philip Wood, Tim Seaver, and Ken Adelman. 

SEE ALSO 

netstat(l), ping(8) 

BSD 4.3, 6 Junel993 


tune2fs 

tune 2 ts— Adjust tunable filesystem parameters on second extended filesystems. 

SYNOPSIS 

tune2fs [ -1 ][- c max-mount - counts ][- e errors-behavi or ] 

[-i i nterval- between-checks ][ -m reserved- bl ocks-percentage ] 

[-r reserved- bl ocks-count ][- u user ][-g group ]device 

DESCRIPTION 

tune 2 fs adjusts tunable filesystem parameters on a Linux second extended filesystem. 

N ever use tune 2 fs on a read/write mounted filesystem to change parameters! 

OPTIONS 

-c ma*- mount - counts Adjust the maximal mounts count between two filesystem checks. 

-e errors-behavi or C hange the behavior of the kernel codewhen errors are detected, errors-behavi or can 

be one of the following: 

continue Continuenormal execution. 

remount-ro RemountthefiIesystem read-only. 

Causes a kernel panic. 


panic 



tunelp 



-g group 


-i i nterval - bet ween- checks [d|m J w] 
-1 

-m reserved - bl ocks-percentage 
-r reserved-bl ocks-count 
-u user 


Set the user group that can benefit from the reserved blocks group can be a numerical 
GID or a group name 

Adjust the maximal time between two filesystem checks. No postfix or d results in days, 
nr in months, and w in weeks. A valueof 0 will disablethetime-dependent checking. 

List the contents of the filesystem superblock. 

Adjust the reserved blocks percentage on the given device. 

Adjust the reserved blocks count on the given device 

Set the user who can benefit from the reserved blocks, user can be a numerical U ID or a 
username. 


BUGS 

Wedidn'tfind any bugs. Perhaps there are bugs, but it's unlikely. 

WARNING 

U sethis utility at your own risk. You're modifying filesystems. 

AUTHOR 

tune 2 fs was written by Remy Card (card@masi.ibp.fr), thedeveloper and maintainer of theext 2 filesystem. tune 2 fs 
usestheext 2 fs library written byTheodoreT'so (tytso@mit.edu). This manual page was written by C hristian Kuhtz 
(chk@data-hh.Hanse.DE). Time-dependent checking was added by U we Ohse (uwe@tirka.gun.de). 

AVAILABILITY 

tune 2 fs is avai I able for anonymous FT P from ftp. ibp.fr and tsx -1 1 .mit.edu in / pub/linux/ packages/ext 2 f s. 

SEE ALSO 

dumpe2fs(8), e2fsck(8), mke2fs(8) 

Verson 0.5b , N ovember 1994 


tunelp 

tuneip— Set various parameters for the Ip device. 

SYNOPSIS 

tunelp device [-i IRQ [ -t TIME j -c CHARS 
| -w WAI T | -a [on|off] j -o [on|off] [ -C [on|off] 

! -r [ -s | -q [on[off] ] 

DESCRIPTION 

tuneip sets several parameters for the /dev/ip? devices, for better performance (or for any performance at all, if your printer 
won't work without it...). Without parameters, tuneip tells whether the da/ice is using interrupts, and if so, which one. 

With parameters, tuneip sets thedevice characteristics accordingly. Theparameters are as follows: 

-i <i rq> The IRQ to use for the parallel port in question. If this is set to something nonzero, -t 

and -c have no effect. If your port does not use interrupts, this option will make 
printing stop, tuneip -i 0 restores non-interrupt driven (polling) action, and your 
printer should work again. If your parallel port does support interrupts, interrupt-driven 
printing should be somewhat faster and efficient and will probably be desirable. 

-t <ti me > T he amount of time in jiffies that the driver waits if the printer doesn't take a character 

for the number of tries dictated by the -c parameter. 10 is the default value. If you want 
the fastest possible printing and don't care about system load, you can set this to 0 . If 
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-c <CHARS> 


-w <WAI T > 


-a [on|off] 


-o [on|off] 


-C [on]off] 


-r 

-q [on|off] 


you don't care how fast your printer goes or are printing text on a slow printer with a 
buffer, then 500 (5 seconds) should be fine and will give you very low system load. This 
value generally should be lower for printing graphics than text, by a factor of approxi¬ 
mately 10, for best performance. 

T he number of times to try to output a character to the printer before sleeping for 
-t <ti me >. It is the number of times around a loop that tries to send a character to the 
printer. 120 appears to be a good value for most printers 250 is the default because there 
are some printers that require a wait this long, but feel free to change this. If you havea 
very fast printer like an H P Laserjet 4, a value of 10 might make more sense. If you have 
a really old printer, you can increase this. 

Setting -t <ti me > to 0 is equivalent to setting -c <chars > to infinity. 

T he busy loop counter for the strobe signal. Although most printers appear to be able to 
deal with an extremely short strobe, someprinters demand alongerone. Increasingthis 
from the default 0 might make it possible to print with those printers. This can also 
make it possible to use longer cables. 

This is whether to abort on printer error; the default is not to. If you are sitting at your 
computer, you probably want to beableto see an error and fix it and have the printer go 
on printing. On the other hand, if you aren't, you might rather that your printer spooler 
find out that the printer isn't ready, quit trying, and send you mail about it. The choice 
is yours. 

This option is much like - a. It makes any open 0 of this device check to see that the 
device is online and not reporting any out-of-paper or other errors. This is the correct 
setting for most versions of ipd. 

This option adds extra ("careful") error checking. When this option is on, the printer 
driver will ensure that the printer is online and not reporting any out-of-paper or other 
errors before sending data. This is particularly useful for printers that usually appear to 
accept data when turned off. 

This option returns the current printer status, both as a decimal number from 0 to 255 
and as a list of active flags. When thisoption is specified, -q oft, turning off thedisplay 
ofthecurrent IRQ, isimplied. 

- 0 , -c, and -s all require a Linux kernel version of 1.1.76 or later. 

Thisoption resets the port. It requiresa Linux kernel version of 1.1.80 or later. 
Thisoption sets pri nting the display of the current IRQ setting. 

Cohesive Systems 26 August 1992 


update_state 

update_state — U pdate system state. 

SYNOPSIS 

update_state 

DESCRIPTION 

update_state updates a bunch of system states. It takes a long time to execute and would be suitablefor execution in act-on 
job. 

Currently, update_state performs the followi ng functions: updates the locate database (in /usr/iib/iocate), updates the 
whatis database(in /usr/man, /usr/local/man, /usr/X386/man, and /usr/interviews/man), and updates theT eX ls-R cache file 
(in /usr/lib/texmf). 



UUCICO 



BUGS 

The script expects things to be where the FSST N D says the/ are. For example if you havemakewhatis(8) in /usr/iib, where 
it is traditionally, then you lose, because it should be in /usr/bin. 

SEE ALSO 

cron(8), find(l), locate(l) 

AUTHOR 

Rik Faith (faith@cs.unc.edu) 

Linux 1.0 8, July 1994 


uucico 

uucico— UUCP file transfer daemon. 

SYNOPSIS 

uucicc [ options ] 

DESCRIPTION 

The uucico daemon processes file transfer requests queued by uucp(l) and uux(l). It is started when uucp or uux is run (unless 
they are given the -r option). It is also typically started periodically using entries in thecrontab tables. 

When invoked with -ri, --master, -s, --system, or -s, thedaemon will place a call to a remote system, running in master 
mode. Otherwise, thedaemon will start in slave mode, accepting a call from a remote system. Typically, a special login name 
will beset up for UUCP, which automatically invokes uucico when a call is made. 

When uucico terminates, it invokestheuuxqt(8) daemon, unless the -q or --nouuxqt option isgiven; uuxqt(8) executes any 
work orders created by uux(l) on a remote system and any work orders created locally that have received remote files for 
which they were waiting. 

If a call fails, uucico will usually refuse to retry the call until a certain (configurable) amount of time has passed. This may be 
overridden by the -f, -force, or -s option. 

The -l, - -prompt, -e, or - -loop options may be used to force uucico to produce its own prompts of login: and PassworO:. 
When another daemon calls in, it will see these prompts and log in as usual. Thelogin name and password are usual ly 
checked against a separate list kept specially for uucico rather than the/etc/passwo file; it is possible on some systems to 
direct uucico to use the /etc/passwo file. The -l or - prompt option will prompt once and then exit; in this mode theUUCP 
administrator or the superuser may use the -u or - login option to force a login name in which case uucico will not prompt 
for one. The -e or -loop option will prompt again after the first session is over; in this mode, uucico will permanently control 
a port. 

If uucico receives a sigquit, sigterm, or sigpipe signal, it will cleanly abort any current conversation with a remote system 
and exit. I fit receives a sighup signal, itwill abort any current conversation, but will continue to place calls to (ifinvoked 
with - ri or - master) and accept calls from (if invoked with -e or -loop) other systems. If it receives a sigint signal, itwill 
finish the current conversation but will not place or accept any more calls. 

OPTIONS 

The following options may be given to uucico: 

-ri, - --master Start in master mode (call out to a system); implied by -s, - -system, or -s. If no system 

is specified, call any system for which work is waiting to be done. 

Start in slave mode. This isthe default. 

Call the named system. 


-r0, - --slave 

-s system, ---system system 
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-S system 
-f, - - -force 
-1, - - -prompt 


-p port, - - -port port 
-e, - - -loop 

-w, - - -wait 


-q, ---nouuxqt 
-c, - - -quiet 


-C, - --ifwork 
-D, - - -nodetach 


-u name, - - -login name 


-z, - - -try-next 
-i type, - - -stdin t ype 


-x type, -X type, - --debug type 


-I file, - - -config file 

-v, - --version 
--help 
-u login 


Call the named system, ignoring any required wait. This is equivalent to -s system -f. 
Ignore any required wait for any systems to be called. 

Prompt for login name and password using login: and Password:. This allows uucico to 
be easily run from inetd(8). Thelogin nameand password are checked against the 
UUCP password file, which probably has no connection to the file /etc/passwd. The 
--login option may beused to forcea login name, in which caseuucico will only 
prompt for a password. 

Specify a port to call out on or to listen to. 

Enter endless loop of login/password prompts and slave mode daemon execution. The 
program will not stop by itself; you must use kiii(l) to shut it down. 

After calling out (to a particular system when -s, - -system, or -s is specified or to all 
systems that have work when just -ri or - master is specified), begin an endless loop as 
With - -loop. 

D o not start the uuxqt(8) daemon when finished. 

If no calls are permitted at this time, then don't make the call, but also do not put an 
error message in the log file and do not update the system status (as reported by 
uustat(l)). This can be convenient for automated polling scripts, which may want to 
simply attempt to call every system rather than worry about which particular systems 
may be called at the moment. This option also suppresses the log message indicating 
that there is no work to be done. 

Only call thesystem named by -s, --system, or -s if there is work for that system. 

Do not detach from the controlling terminal. N ormally, uucico detaches from the 
terminal before each call out to another system and before invoking uuxqt. This option 
prevents this 

Set thelogin name to use instead of that of the invoking user. This option may only be 
used bytheUUCP administrator or the superuser. If used with -prompt, thiswill cause 
uucico to prompt only for the password, not the login name. 

If a call fails after the remote system is reached, try the next alternate rather than simply 
exiting. 

Set the type of port to use when using standard input. The only support port type is 
TLI, and this is only available on machines that support the T LI networking interface. 
Specifying -ini causes uucico to useTLI calls to perform I/O. 

T urn on particular debugging types. The following types are recognized: abnormal, chat, 
handshake, uucp-proto, proto, port, config, spooldir, execute, incoming, outgoing. 

M ultiple types may be given, separated by commas, and the - -debug option may appear 
multipletimes. A number may also be given, which will turn on that many types from 
theforegoing list; for example, --debug 2 is equivalent to --debug abnormal,chat. 

The debugging output is sent to the debugging file usually one of /usr/spooi/uucp/Debug, 
/usr/spool/uucp/DEBUG, Or /usr/spool/uucp/.Admin/audit.local. 

Set configuration file to use. Thisoption may not be available depending on how 
uucico was compiled. 

Report version information and exit. 

Print a help message and exit. 

Thisoption is ignored. It isonly included because some versions of uucpd invokeuucico 
with it. 


The filenames may be changed at compilation time or by the configuration file, so these are only approximations: 
/usr/iib/uucp/config Configuration file. 

/usr/iib/uucp/passwd D efault UUCP password file. 



vmstat 


1417 


/usr/spool/uucp 
/usr/spool/uucp/Log 
/usr/spool/uucppublic 
/usr/spool/uucp/Debug 


UUCP spool directory. 

UUCP log file. 

Default UUCP public directory. 
Debugging file. 


SEE ALSO 

kill(l), uucp(l), uux(l), uustat(l), uuxqt(8) 

AUTHOR 

Ian LanceTaylor (ian@airs.com) 


Taylor UUCP 1.05 


vmstat 

vmstat — Report virtual memory statistics. 

SYNOPSIS 

vmstat [ -n ] [delay [count ] ] 

DESCRIPTION 

vmstat reports information about processes, memory, paging, block 10, traps, and CPU activity. 

The first report produced gives averages since the last reboot. Additional reports give information on a sampling period of 
length delay. The process and memory reports are instantaneous in either case. 

OPTIONS 

The -n switch causes the header to be displayed only once rather than periodically. 

delay is the delay between updates in seconds. If no delay is specified, only one report is printed with the average values si nee 
boot. 

count isthenumber of updates. If no count is specified and del ay isdefined, count defaults to infinity. 

FIELD DESCRIPTIONS 


Procs 


r 

b 

w 

M emory 

The number of processes waiting for runtime 

The number of processes in uninterruptible sleep. 

T he number of processes swapped out but otherwise runnable. 
This field is calculated, but Linux never desperation swaps. 

swpd 

The amount of virtual memory used (KB). 

free 

The amount of idle memory (KB). 

buff 

The amount of memory used as buffers (K B). 

Swap 

si 

Amount of memory swapped in from disk (KB/s). 

so 

Amount of memory swapped to disk (KB/s). 
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bi 
bo 

System 

in 
cs 

CPU (These are percentages of total CPU time.) 

us 
sy 
id 

NOTES 

vmstat does not require special permissions. 

These reports are intended to help identify system bottlenecks. Linux vmstat does not count itself as a running process. 

All Linux blocks are currently 1KB, except for CD-ROM blocks, which are 2KB. 

FILES 

/proc/meminfo 

/proc/stat 

/proc/*/stat 

SEE ALSO 

ps( 1), top(l), free(l) 

BUGS 

vmstat does not tabulate the block 10 per device or count the number of system calls. 

AUTHOR 

Written by H enry Ware (aii72@ytn.ysu.edu) 

Throatwobbler Ginkgo Labs 27 July 1994 

vipw 

vipw — Edit the password file. 

SYNOPSIS 

vipw 

DESCRIPTION 

vipw edits the password file after setting the appropriate locks and does any necessary processing after the password file is 
unlocked. If the password file is already locked for editing by another user, vipw will ask you to try again later. The default 
editor for vipw isvi(l). 


Blocks sent to a block device(block^s). 

Blocks received from ablock device (block^s). 

The number of interrupts per second, including the clock. 
T he number of context switches per second. 

U ser ti me. 

System time. 

Idletime. 




zic 

ENVIRONMENT 

If the following environment variable exists, it will be utilized by vipw: 

editor The editor specified by the string, editor will be invoked instead of the default editor 

vi(l). 

SEE ALSO 

passwd(l), vi(l), passwd(5) 

HISTORY 

The vipw command appeared in BSD 4.0. 

BSD 4,16 March 1991 

zdump 

zdump — T i me zone dumper. 

SYNOPSIS 

zdump [ -v ][-c cutoffyear ] [ zonename ... ] 

DESCRIPTION 

zdump prints the current time in each zonename named on the command line 
T hese options are available: 

-V 


-c cutoffyear 

SEE ALSO 

newctime(3), tzfile(5), zic(8) 

zic 

zic— Time zone compiler. 

SYNOPSIS 

zic [ -v ][-d directory ] [ -1 localtime ] [ - p posixrules ] 

[-L I eapsecondfi I ename ] [ - s ] [ -y command ] [filename ... ] 

DESCRIPTION 

zic reads text from the files named on the command line and creates the time conversion information files specified in this 
input. If a filename is-, thestandard input is read. 

T hese options are available: 

-d di rectory C reate time conversion information files in the named directory rather than in the 

standard directory named below. 


For each zonename on the command line, print the current time, the time at the lowest 
possible time value, the time one day after the lowest possible time value, the times both 
one second before and exactly at each detected time discontinuity, the time at one day 
less than the highest possible time value, and the time at the highest possible time value. 
Each li ne ends with isdst=i if thegiven time is D aylight Savi ng T i me or isdst=c 
otherwise. 

C ut off the verbose output near the start of the given year. 
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-i ti mezone Use the given time zone as local time, zic will act as if the input contained a link line of 

the form. 

Link t i mezone I ocal t i me . 

-p ti mezone Use the given time zone's rules when handling PO SI X-format time zone environment 

variables, zic will act as if the input contained a link line of the form. 

Link t i mezone posixr ul es . 

-l leapsecondfiiename Read leap second information from the file with the given name. If this option is not 

used, no leap second information appears in output files. 

-v C omplain if a year that appears in a data fi le is outside the range of years representable 

by time(2) values. 

-s L imit time values stored i n output fi les to values that are the same whether they're taken 

to be signed or unsigned. You can use this option to generate SVVS-compatible files. 

-y command Usethegiven command rather than yearistype when checking year types. 

Input lines are made up of fields. Fields are separated from one another by any number of whitespace characters. Leading 
and trailing whitespace on input lines is ignored. An unquoted sharp character (#) in the input introduces a comment that 
extends to the end of the line the sharp character appears on. W hitespace characters and sharp characters may be enclosed in 
double quotes (") if they're to be used as part of afield. Any line that is blank (after comment stripping) is ignored. N on- 
blank lines are expected to be of one of three types: rule lines, zone lines, and link lines. 

A rule line hastheform 

Rule NAME FROM TO TYPE IN ON AT SAVE LETTER/S 

For example: 

Rule US 1967 1973 - Apr lastSun 2:00 1:00 D 

T he fields that make up a rule line are 

name Givesthe (arbitrary) name of the set of rules this rule is part of. 

from Gives the first year in which the rule applies. Any integer year can be supplied; the 

Gregorian calendar is assumed. The word minimum (or an abbreviation) meansthe 
minimum year representable as an integer. The word maximum (or an abbreviation) means 
the maximum year representable as an integer. Rules can describe times that are not 
representable as time values, with the unrepresentable times ignored; this allows rules to 
be portableamong hosts with differing time value types. 

to Gives thefinal year in which the rule applies. In addition to minimum and maximum, 

the word only (or an abbreviation) may be used to repeat the value of the from field. 
type Gives the type of year in which the rule applies. If type is-, the rule applies in all years 

between from and to inclusive. If type is something else then zic executes the command 

yearistype year type 

to check thetype of ayear. An exit status of zero istaken to mean that the year isof the 
given type; an exit status of one is taken to mean that the year is not of the given type. 
in N amesthemonth in which the rule takes effect. Month names may be abbreviated. 

on Givesthedayonwhichtheruletakeseffect. Recognized forms include 

5 The fifth of the month 

lastsun The last Sunday in the month 

lastMon T he last M onday in the month 

sun>=8 First Sunday on or after the eighth 

sun<=25 Last Sunday on or before the 25th 

N amesof days of the week may be abbreviated or spelled out in full. 
Note that there must be no spaces within theoN field. 




z/'c 



at Givesthetimeof day at which the rule takes effect. Recognized formsinclude 

2 Timein hours 

2:00 Timein hours and minutes 

15:00 24 -hour format time (for times after noon) 

i:28:i4 Timein hours, minutes, and seconds 

Any of these forms may be followed by the letter w if the given time is local wall clock 
time, s if the given timeislocal standard time, or u (or g or z) if the given timeis 
universal time; in the absence of an indicator, wall clock time is assumed. 
save Gives the amount of time to be added to local standard time when the rule isin effect. 

This field has the same format as the at field (although, of course, thew and s suffixes 
are not used). 

letter/ s Gives the variable part (for example, the s or d in E ST or EDT) of time-zone abbrevia¬ 

tions to be used when this rule is in effect. If this field is-, the variable part is null. 


A zone line has the form 

Zone NAME GMTOFF RULES/SAVE FORMAT [UNTIL] 

For example: 

Zone Australia/Adelaide 9:30 Aus CST 1971 Oct 31 2:00 

Thefields that make up azonelineare 

name Thenameof thetimezone. Thisisthenameused in creating the time con version 

information fileforthezone. 

gmtoff The amount of time to add to GMT to get standard timein this zone. This field has the 

same format as the at and save fields of rule lines; begin the field with a minus sign if 
time must be subtracted from GMT. 

rules/save T he name of the rulesthat apply in the time zone or, alternately, an amount of time to 

add to local standard time If thisfield is-, standard time always applies in the time 
zone. 

format The format for time zone abbreviations in this time zone. The pair of characters %s is 

used to show where the variable part of thetimezone abbreviation goes. Alternately, a 
slash (/) separates standard and daylight abbreviations. 

unti l Thetimeat which theGMT offset orthe rules changefor a location. It is specified asa 

year, a month, a day, and a time of day. If this is specified, thetimezone information is 
generated from thegiven GMT offset and rule change until thetime specified. 

The next line must be a continuation line; this has the same form as a zone line except 
that the string zone and the name are omitted because the continuation line will place 
information starting at the time specified as the unti l field in the previous line in the file 
used by the previous line. Continuation lines may contain an unti l field, just as zone 
lines do, indicating that the next line is a further continuation. 


A link line hastheform 

Link LI NK-FROM LI NK-TO 

For example: 

Link US/Eastern EST5EDT 

Then nk- from field should appear as the name field in some zone line; the l i nk-to field is used as an alternate name for that 
zone. 

Except for continuation lines, lines may appear in any order in the input. 

Lines i n the fi le that descri be leap seconds have the followi ng form: 
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Leap YEAR MONTH DAY HH:MM:SS CORR R/5 

For example: 

Leap 1974 Dec 31 23:59:60 + S 

TheYEAR, month, day, and hh: mm: ss fields tell when theleap second happened. T he corr field should be + if asecond was 
added or - if asecond was skipped. The r/ s field should be (an abbreviation of) stationary if theleap second time given by 
the other fields should be interpreted asGMT or (an abbreviation of) Roiling if theleap second time given by the other 
fields should be interpreted aslocal wall clock time. 

NOTE 

For areas with more than two types of local time, you may need to use local standard time in the at field of the earliest 
transition time'sruleto ensurethat the earliest transition time recorded in thecompiled file is correct. 

FILE 

/usr/local/etc/zoneinto standard directory used for created files. 

SEE ALSO 

newctime(3), tzfile(5), zdump(8) 
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addjtimer, deljtimer, initjtimer 

addjtimer, deljtimer, init_timer —M an age event timers. 

SYNOPSIS 

#include <asm/param.h> 

#include <linux/timer.h> 

extern void addjtimer(struct timer_list * timer); 
extern int del_timer(struct timer_list * timer); 
extern inline void init_timer(struct timer_list * timer); 

DESCRIPTION 

addjtimer schedules an event, adding it to a linked list of events maintained by the kernel. dei_timer deletes a scheduled 
event, t i me r points to a 

struct timer_list { 

struct timer_list *next ; 

struct timer_list *prev; 

unsigned long expi res ; 

unsigned long data; 

void (*funct i on)(unsigned long); 

}; 

init_timer sets next and pr ev to null. T his is requi red for the argument of add_timer. e*pi res is the desired duration of the 
timer in jiffies, where there are hz (typically 100) jiffies per second. When the timer expires, f unct i on is called with data as 
its argument. It is the responsibility of function to delete the event. If the same function is managing several timers, the 
argument can be used to distinguish which oneexpired. 

RETURN VALUE 

dei_timer returns zero on error— if next or pr ev are not null, but the timer was not found. dei_timer also sets ex pi res to the 
time remaining before the timer expi res and sets next and pr ev to null. Thus, calling dei_timer followed immediately by 
addjtimer is a no-op provided a kernel tick does not occur between the two calls 

AUTHOR 

LinusTorvalds 

Linux 1.2.8, 31 May 1995 


adjust_clock 

adjust_ciock— Adjusts startup time counter to tick in GMT. 

SYNOPSIS 

linux/kernel/sys.c 
void adjust_clock(); 

DESCRIPTION 

This routine adjusts the startup time by adding the time zone information to it. The goal is to get the startup time ticking in 
GMT time. 

NOTES 

This routine is called from settimeofday(2) when the time-zone information is first set. 



filejable 

AUTHOR 

T heodoreT 'so (tytso@mit.edu) 

SEE ALSO 

settimeofday(2) 

Linux0.99.10, 7July 1993 

ctrl_alt_del 

ctn_ait_dei— Routes the keyboard interrupt Ctrl-hAlt+D el key sequence. 

SYNOPSIS 

linux/kernel/sys.c 
void ctrl_alt_del(void); 

DESCRIPTION 

This simple routine tests the variable c_a_d for a true/false condition. If it is true, a hard reset is done by the system. 
Otherwise, asignal siGiNTissenttotheprocesswiththeprocessID 1, usually a program called init. 

WARNINGS 

Thisroutineisin interrupt mode. It cannot sync o your system. Data loss may occur. It is recommended that you configure 
your system to send asignal to init, where you can control the shutdown. 

NOTES 

T he default of this function isto do hard resets immediately. 

AUTHOR 

LinusTorvalds 

SEE ALSO 

reboot(2), reset_hard_now(9), sync(2) 

Linux0.99.10, 6July 1993 

filejable 

fiie_tabie— Detailed description of the table and table entry. 

SYNOPSIS 

From#include <linux/fs.h> 

struct file { 
mode_t f_mode; 

dev_t f_rdev; /* needed for /dev/tty */ 

off_t f_pos; 

unsigned short f_flags; 

unsigned short f_count; 

unsigned short f_reada; 

struct file *f_next, *f_prev; 

struct inode *f_inode; 
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struct file_operations *f_op; 

}; 

From linux/fs/file_table.c 

struct file *first_file; 
int nr_files = 0; 

DESCRIPTION 

The file table is fundamentally important to any U NIX system. It is where all open files (Linux includes closed files as well) 
are stored and managed by thekernel. For Linux, you can hardly do anything without referencing it in someway. 

Linux stores its file table as a double circular linked list. The root pointer to the "head" of this list isfirst_tiie. Also, a count 
of how many entries are in thefiletable ismaintained, called nr_fiies. Under thisscheme, thefiletablefor Linux could be 
as large as memory could hold. Unfortunately, this would be unmanageable in most cases. Your computer would be in the 
kernel most of the time when processes are more important. T o keep this from happening, nr_fiies is tested against nr file 
to limit the number of fi le table entries. 

U N D ERSTAN D IN G TH E STRU CTU RE 0 F THE FILE TABLE 

The file table is organized as a double circular linked list. Imagine a circle of people with everyone facing the same direction. 
Each person isfacing so that onearm isin the circle and theother arm is outside the circle. N ow, if each person put hisor 
her right hand on the shoulder of the person in front of him or her and if each person touched the person behind him or her 
with hisor her left hand. You have formed two circles of arms, one inside and theother outside. The right armsrepresent 
poi nters to the next entry (or person). T he left arms represent pointers to the previous entry (or person). 

THE FILE STRUCTURE, A FILE TABLE ENTRY 

At first glance, a table entry looks quite simple. An entry contains how a file was opened, what tty device, a reference count, 
pointers to other entries, pointer to v-node(thevfs i-node) filesystem-specific i-node information, and so on. 

f_mode 
00 
01 
10 
11 
f_rdev 
f_pos 
f_flags 
f_count 
f_reada 
f_next, f_prev 
f_inode 
f_op 

AUTHOR 

LinusTorvalds 

SEE ALSO 

insert_file_free(9), remove_file_free(9), put_last_free(9) grow_files(9), file_table_init(9), get_empty_filp(9) 

Linux 0.99.10,11 July 1993 


After AN D ingwith o accmode, this is what bits 0 and 1 mean: 

N o permissions needed 
Read-permission 
Write-permission 
Read-write 

It is used only with tty lines. It contains the major and minor numbers of the tty device. 
The current position in a file if meaningful. 

Storagefortheflagsfrom openo and tcntio 
Reference counter 

This is a Boolean variable where True means that an actual read is needed. 

Pointers to other entries 

Pointer to v-node and filesystem-specific i-node information 
Pointer to a file's operations 



filesystems 


1427 


file_table_init 

fiie_tabie_init— Initializes the file table in the kernel. 

SYNOPSIS 

linux/fs/file_table.c unsigned long file_table_init( 
unsigned long start , unsigned long end); 

DESCRIPTION 

This routine is called from kernei_start() in linux/init/main.c. It sets first_f iie, a struct file pointer, to NULL. This is the 
head of the linked list of open files maintained in the kernel, the infamous file table in all U N IXs. 

RETURN VALUE 

Returns start. 

NOTES 

Because this is part of the kernel's startup routine, it has the option to allocate memory, in kernel space, for itself. It does not 
need to do this and returns the new start of memory for the next initializing section. In this case, start is returned unmodi¬ 
fied. 


AUTHOR 

LinusTorvalds 


Linux0.99.10, 9July 1993 


filesystems 

filesystems— Details the table of configured filesystems. 

SYNOPSIS 

linux/fs/filesystems. c 
From#include <linux/fs.h> 
struct file system type { 

struct super bl ock *(*read_super) (struct super_bl ock *, void *, int); 

char *n a me; 

int requires dev; 

}; 

DESCRIPTION 

This source code makes a data structure call fiie_systems[ ], which contains all the configured filesystems for the kernel. It is 
used primarily in iinux/fs/supen.c for many of the mounting of filesystems functions. 

THEMEANINGS 

This first member, in struct fi i e_system_t ype , is a function pointer to a routine that will read in the super _bi ock. A 
superbl ock generically means an i-node or special place on the device where information about the overall filesystem is 
stored. 

The name is just the string representation of the name of a specific filesystem, such as ext 2 or minix. 

The final member, i nt_requi res. dev, is a Boolean value. If it is True, then the filesystem requires a block device. For False, it 
is unclear what happens, but an unnamed device is used, such as proc and nfs. 
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AUTHOR 

LinusTorvalds 


Linux 0.99.10,12 July 1993 


get_empty_filp 

get_empty_fiip— Fetches an unreferenced entry from thefiletable. 

SYNOPSIS 

linux/fs/file table.c 

struct file *get_empty_filp(void); 

DESCRIPTION 

This routine will seek out an entry that is not being referenced by any processes. If none are found, then it will add new 
entries to thefiletable minimum of nr_file entries. 

NOTES 

D ueto grow_tiies(), a whole page of entries is created at onetime. This may make more than nrfile entries. Also when an 
unreferenced entry is found, it is moved to the "end" of thefiletable. This heuristic is used to speed up finding unreferenced 
entries. 

RETURN VALUE 

null— N o entries were found and thefiletable isfull. 

Returns a pointer to the entry in thefiletable. 

AUTHOR 

LinusTorvalds 

SEE ALSO 

grow_files(9) 

Linux 0.99.10,12 July 1993 


growjfiles 

grow_fiies— Adds entries to the file table. 

SYNOPSIS 

linux/fs/file table.c 
void grow_files(void); 

DESCRIPTION 

This function adds entries to thefiletable First, it allocates a page of memory. It fills the entire page with entries, adding 
each to thefiletable. 

AUTHOR 


LinusTorvalds 



insert file free 



SEE ALSO 

insent_file_free(9), remove_file_free(9), put_last_fnee(9) 


Linux 0.99.10,12 July 1993 


in_group_p 

in_group_p — Searches group IDsfora match. 

SYNOPSIS 

linux/kernel/sys.c 

int in_group_p(gid_t grp); 

DESCRIPTION 

Searches supplementary group ID sand the effective group ID for a match with grp. 

RETURN VALUE 

RetumsTrue (i) if found; otherwise, false ( 0 ). 

AUTHOR 

LinusTorvalds 

SEE ALSO 

getgroups(2), getgid(2), getregid(2), setgid(2), setregid(2), setgroups(2) 

Linux0.99.10, 7]ulyl993 


insert_file_free 

insert_fiie_f ree— Adds a fi le entry into the fi le table. 

SYNOPSIS 

linux/fs/file_table.c 

static void insert_file_free(struct file *fiI e); 

DESCRIPTION 

T his nightmare of pointers adds fi 1 e into the file table with the root pointer at fi 1 e. This is a building block of thefile table 
management. 

AUTHOR 

LinusTorvalds 

SEE ALSO 

file_table_init(9), remove_file_free(9), put_last_free(9) 

See fiie_tabie(9) for details on the file table structure. 


Linux 0.99.10 
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kernel_mktime 

kernei_mktime — C onvert startup struct mktime into the number of seconds since 00:00:00 J anuary 1,1970. 

SYNOPSIS 

linux/kernel/mktime.c 

long kerneljnktime(struct mktime * time); 

DESCRIPTION 

This routi ne is called from time_init (void), linux/init/main.c. kerneljnktime () Converts struct mktime (initialized from 
CMOS) into an encoded long. 

CONVERSION METHOD 

First an array, month[i 2 ], is created, holding how many seconds have passed to reach a peculiar month for a leap year. N ext, 
it subtracts 70 from the current year, making 1970 the beginning year. It is math magic after this point; please look yourself. 
If you know why it does this, then send e-mail (seenroff source). 

RETURN VALUE 

Returns the encoded timein a long. 

FILES 

linux/kernel/mktime.C homeof routine 

NOTES 

T his routi ne is called only during startup of the kernel. 

H istorically, the value (encoded long) counts the number of secondssi nee the Epoch, which occurred at 00:00:00 January 1, 
1970, and is called Coordinated Universal Time(UTC). In older manuals, this a/ent is called Greenwich M ean Time 
(GMT). 

WARNINGS 

kernei_mktime () doesn't check to see if the year is greater than 1969. Be sure your CM OS is set correctly. It is customary to 
set on-board clocks to GMT and let processes who ask for the time to convert it to local time, if necessary. 

RESTRICTIONS 

For kernel use only. 

AUTHOR 

LinusTorvalds 

Linux0.99.10, 5July 1993 


proc_sel 

proc_sei— Select a process by a criterion. 

SYNOPSIS 


linux/kernel/sys.c 
#include <linux/resource.h> 

static int proc_sel(struct task_struct *p, int which, int who); 



remove file free 



DESCRIPTION 

Compares a task p to supplied information or the current task in some aspect of priority. If who is zero, the comparison is task 
p and the current task. Otherwise, who and *p arethesupplied information for the comparison. 

OPTIONS 

Valid values of whi ch: 

PRIO_PROCESS 

PRIO_PGRP 
PRIOJJSER 

RETURN VALUE 

Returns truth values ( 0 , 1 ). 

AUTHOR 

LinusTorvalds 

SEE ALSO 

sys_setpriority(2), sysjetpriority(2) 

Linux0.99.10, 7July 1993 


Compares process ID numbers. There is an exception here. If who isnot zero and task p is 
the current task, then True is always returned. 

C ompares process group leader numbers. 

Compares user ID numbers. 


put_file_last 

put_f iie_iast — M oves a fi le to the "end" of the file table. 

SYNOPSIS 

linux/fs/file table.c 

static void put_last_free(struct file *f i I e); 

DESCRIPTION 

This function will removef i 1 e from the file table and insert it again at the end. You can access by 
first_file->prev 

AUTHOR 

LinusTorvalds 

SEE ALSO 

insert_file_f ree(9), remove_file_f reef9) 

Linux 0.99.10,11 July 1993 


remove_file_free 

remove_t iie_f ree — Remove a file table entry from thelinked list. 

SYNOPSIS 

linux/fs/file table.c 

static void remove_file_free(struct file *fiI e); 
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DESCRIPTION 

This routine removes the file from the table. This is used mostly for moving a file to the "end" of the list. 

AUTHOR 

LinusTorvalds 

SEE ALSO 

insert_file_freef9), put_file_last(9) 
































































































































































































■ * (asterisk), bash special parameters 



Symbols 

* (asterisk), bash special 
parameters, 15 

@ (at sign), bash special 
parameters, 15 
\ (backslash), bash escape 
character, 14 
$ (dollar sign) 

bash special parameters, 15 
expansion, 19 
ftp command, 148 
! (exclamation point) 

bash special parameters, 15 
ftp command, 148 
! command (telnet), 512 
> (greater than sign), 
redirection operator, 21 
- (hyphen), bash special 
parameters, 15 
< (lessthan sign), redirection 
operator, 21 
| (pipeline), bash, 12 

# (pound sign) 

bash comments, 14 
bash special parameters, 15 
? (question mark) 

bash special parameters, 15 
ftp command, 152 
? command 
telnet, 512 
xauth, 591 

_ (underscore), bash special 
parameters, 15 
/ directory, 1236 
0, bash special parameter, 15 
8859-1 character set, 1064 
8859-2 character set, 1064 
8859-3 character set, 1064 
8859-4 character set, 1064 
8859-5 character set, 1065 
8859-6 character set, 1065 
8859-7 character set, 1065 
8859-8 character set, 1065 
8859-9 character set, 1065 
8859-10 character set, 1065 


A 


Abekas YU V bytes, converting 
to portable pixmaps, 731 
abort() function, 892 
abs() function, 892-893 
absolute values, 892-893 
floating-point numbers, 919 
long integers, 960-961 
accept, 740-741 
access, 741-742 
errors, 741 
restrictions, 741 
return value, 741 
access control 

files, changing permissions, 
61-62 

hosts_ access, 1133-1136 
diagnostics 1136 
flies 1133,1136 
operators 1134 
patterns 1133-1134 
remote username lookup, 
1134-1135 
rules 1133 
shell commands 1134 
wildcards 1134 
language extensions, 
1137-1139 
memory, 804-805 
N NTP sites, 1167-1168 
account (ftp command), 148 
acct, 742 

acos() function, 893 
acosh() function, 893-894 
active, 1104-1105 
active.times, 1104-1105 
add (cvs command), 96 
AD D _ AD D RE SS environ¬ 
ment variable, 529 
add_ timer, 1424 
addftinfo, 2 
addgroup, 1258-1259 
addmntent() function, 
935-936 


addresses 

Internet, manipulating, 
953-954 

mail addressing, 1244-1246 
abbreviations 1245 
case sensitivity, 1245 
compatibility, 1245 
postmasters, 1246 
routing, 1245 
physical, accessing, 818 
sed, 476 

virtual memory, remapping, 
805-806 

adduser, 1258-1259 
adduser.conf, 1105 
adjtimex, 742-743 
adjust_ clock, 1424-1425 
admin (cvscommand), 96 
advisory locks, open files 
(applying/removing), 757 
afmtodit, 2-4 
files, 3 
options, 3 
running, 3 
agetty, 1259-1262 
arguments, 1260 
bugs, 1261 
diagnostics, 1261 
files, 1261 
issue escapes, 1261 
options, 1260 
alarm, 744 

alarm clock, setting, 744 
alias (shell command), 35 
aliases, 23-24,1106 
bugs, 1106 
printing, 35 
removing names, 45 
alloca function, 894 
bugs, 894 
return values, 894 
allocating memory, 894, 976 
allow-null_glob_ expansion 
variable (bash), 17 
allow-send-events() action 
(xterm), 714 
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alphasortf) function, 
1012-1013 

American Standard Code for 
Information, seeASC 11 
Andrew Toolkit raster objects, 
converting to portable 
bitmaps, 10 
ANSI C, converting to 
Kernighan & Ritchie, 4 
ansi2knr, 4 

antialiasing portableanymaps, 
381-382 
anytopnm, 4 

append (ftp command), 148 
application resources, 
printing, 5 

applications (client), listing, 
669-670 
appres, 5 
ar, 5-7 

copying, 7 
modifiers, 7 
options, 6-7 

arc cosines, 893 
arc sines, 894-895 
arc tangents, 896 

two variables, 896-897 

arch, 8 

archive, 1262-1263 
archives 

creating, 5-7 
extracting from, 5-7 
indexes (generating), 
437-438 
modifying, 5-7 
shell, creating, 484-487 
arguments 

concatenating, 37 
outputting, 36-37 
reading from standard input, 
586-587 
arithmetic 
evaluation 
bash, 34 

let command, 39 
expansion, bash, 20 



functions 
awk, 168-169 
sn(), 1020-1021 
sinhf), 1021 
sqrt(), 1023 
tan(), 1047-1048 
tanh(), 1048 
performing on portable 
anymaps, 382-383 
arp, 1263 

ARP cache, manipulating, 
1263 
arrays 

awk, 164 

linear searches, 975-976 
searching sorted, 900-901 
sorting, 1000 

articles (news), see tin 
as, 8-9 

ASCII (American Standard 
Code for Information), 1064 
character set, 1214-1216 
graphics, converting to 
portable graymap, 10 
ascii (ftp command), 148 
ascii manual page, 1214-1216 
asciitopgm, 10 
asctime* 984-986 
asctime() function, 910 
asin() function, 894-895 
errors, 895 
return value, 895 
asinh() function, 895 
assemblers, as, 8-9 
assertf) function, 895-896 
asterisk (*), bash special 
parameters, 15 
at sign (@), bash special 
parameters, 15 
atan() function, 896 
atan2() function, 896-897 
atanh() function, 897 
Atari compressed Spectrum 
files, converting to portable 
pixmaps, 494 
Atari D egas PI 1 files, 
converting to portable 
pixmaps, 378 


Atari Degas PI 3 files, 
converting to portable 
bitmaps, 379 

Atari uncompressed Spectrum 
files, converting to portable 
pixmaps, 495-496 
atexit() function, 897-898 
errors, 898 
return value, 898 
atktopbm, 10 
atobm, 49-57 
options, 50 
atof() function, 898 
atoi() function, 898-899 
atol() function, 899 
attributes, file* 59 
authentication 
cidentd, 69-70 
Kerberos authentication, 

461 

pcnfsd, 1355-1356 
pppd, 1366-1367 

authority files (X), xauth 
utility, 587-592 
auto resume variable (bash), 
18” 

AutoCAD slide files, convert¬ 
ing to portable pixmaps, 
490-491 

AUTOSUBSCRIBE environ¬ 
ment variable, 529 
AUTOUNSUBSCRIBE 
environment variable, 530 
awk 

actions, 165-166 
arithmetic functions, 
168-169 

control statements, 167 
fields, 163 
functions, 170 
GNU extensions, 171 
historical features supported 
by gawk, 172 
I/O statements, 167 
operators, 166-167 
patterns, 165-166 
printf statement, 167-168 
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program execution, 162-163 
regular expressions, 166 
sprintf() function, 167-168 
string constants, 169-170 
string functions, 169 
time functions, 169 
variables, 163-165 
arrays 164 
built-in, 163-164 
typing and converaon, 
164-165 

B 


backslashes (\), bash escape 
character, 14 
badblocks, 1264 
banner, 1210 
bash 

aliases, 23-24 
arguments, 11 
arithmetic evaluation, 34 
blanks, 12 
bugs, 46 

command execution, 25 
comments, 14 
compound commands, 13 
case, 13 
list, 13 
while, 13 

control operators, 12 
environments, 25-26 
escape character, 14 
exit status, 26 
expansion, 18-21 
arithmetic, 20 
brace, 19 

command substitution, 20 
history, 33-34 
parameter, 19-20 
pathname, 21 
processsubstitution, 20 
quote removal, 21 
tilde 19 

word splitting, 21 
files, 46 
functions, 23 


history list, 32-33 
invocation, 45-46 
job control, 24-25 
lists, 12-13 
meta characters, 12 
names, 12 
options, 11 
parameters, 14-15 
positional, 14 
qoecial, 14-15 
pipelines (|), 12 
prompting, 26 
quoting, 14 
readline, 27-32 
commands 29-32 
controlling key bindings 
21 

customizing, 21 
denoting keystrokes 21 
macro definitions 28 
parser directives 28-29 
variables, 28 
redirection, 21-23 

duplicating file descriptors 
23 

here-documents 22-23 
input, 22 

opening file descriptors 23 
operators 21 
output, 22 

Standard error output, 22 
Standard output, 22 
reserved words, 12 
shell variables, 15-18 
allow- 

null_glob_e<panson, 11 
autojesume, 18 
BASH,15 

BASH _VERSION, 15 
cdable_vars 18 
CDPATH,16 
command_ oriented_ history, 
11 

ENV, 16 
EUID,15 
FCEDIT, 11 
FIGNORE, 11 


glob_dot_filename$ 11 
histchars 11-18 
HISTCM D, 16 
HISTFILE, 11 
HISTFILESIZE, 11 
history control, 11 
HIST SIZE, 11 
HOME, 16 

hostname_ completion_ file, 
18 

HOSTTYPE, 16 
IFS.16 

IGNOREEOF, 11 
INPUTRC, 11 
LINENO, 15 
MAIL, 16 

MAIL_WARNING, 16 
MAILCHECK, 16 
MAILPATH, 16 
no_edt_on_failed_exec, 

18 

noclobber, 18 
nolinks 18 
notify, 11 
OLDPWD, 15 
OPTARG,16 
OPTERR, 11 
OPTIND, 16 
OSTYPE, 16 
PATH,16 
PPID, 15 

PROMPT _COMMAND, 
11 

PS1, 16 
PS2, 16 
PS3,11 
PS4,11 
PWD, 15 
RANDOM, 15 
REPLY, 15 
SECONDS, 15 
SHLVL, 15 
TMOUT, 11 
UID,15 
signals, 25 

simple commands, 12 
words, 12 







BASH variable (bash), 15 
BASH_VERSION variable 
(bash), 15 

bcmp() function, 899-901 
bcopy() function, 900-901 
BD F fonts, generating, 
146-147 

bdflush, 744-745 
errors, 745 
return value, 745 

bdftopcf, 47 
beforelight, 47-48 
bell (ftp command), 148 
bell() action (xterm), 713 
bell-style variable (readline), 
28 

Bennet Yee face files, see face 
files 

Bentleyizing portable 
graymaps, 369 
Bessel functions, 959-960 

j0( ), 959 
jl(). 959 
jn(), 959 
y0(), 959 
yl(), 959 
yn(), 959 

bg (shell command), 35 
bibliographic databases, 219 

fields, 219 

inverted indexes, 209-210 
searching, 210, 292-293 

biff, 48 

biff server, 1274-1275 
/bin directory, 1236 
binary (ftp command), 148 
binary datesftimes, converting 
to ASCII, 909-911 
binary files, encoding/ 
decoding, 565-566 
binary streams, input/output 
(getting), 926-927 
binary trees 

deleting items, 1056 
searching, 1056 
traversing, 1056 


bsearchf) function 



bind, 35, 745-746 

errors, 745-746 
return value, 745 

binding names to sockets, 
745-746 

bioradtopgm, 48-49 

bugs, 49 
options, 49 

bit sets, finding first in words, 
921 

Bitmap Distribution Format 
fonts, converting to Portable 
Complied Format, 47 
bitmap widget, 56-57 
bitmaps, 49-57 

CM U, converting to 
portable, 71 
color, 56 
conversion, 49 
cutting and pasting, 54 
display, 50 

drawing commands, 51-53 
Edit menu commands, 

53-54 

editing images, 50-51 
File menu commands, 53 
options, 49-50 
U niversal Product Code, 
creating, 368 
widgets, 54-56 
blanks (bash), 12 
block buffered streams, 1016 
block special files, creating, 
325 

BMP files, converting to 
portable pixmaps, 57 
bmptoppm, 57 
bmtoa, 49-57 
/boot directory, 1236 
boot-time parameters 
(kernel), see bootparam 
bootparam, 1216-1224 
Adaptec configurations, 
1219-1220 

argument list, 1216-1217 
BusLogic configuration, 

1220 


busmouse driver parameters, 
1224 

CD-ROM parameters, 
1222-1223 

debug argument, 1217 
Ethernet device parameters, 

1223 

floppy disk driver param¬ 
eters, 1223-1224 
future domain configura¬ 
tion, 1220 

hard disk parameters, 
1220-1221 

mem=argument, 1218 
no-hit argument, 1217 
no387 argument, 1217 
Pro Audio configuration, 
1220 

ramdisk= argument, 1218 
reboot=warm argument, 
1218 

reserve= argument, 

1217- 1218 

ro argument, 1217 
root= argument, 1217 
rw argument, 1217 
SCSI device arguments, 

1218- 1219 

SCSI tape configuration, 

1219 

Seagate ST -Ox configuration, 

1220 

sound driver parameters, 

1224 

TrantorT128 configuration, 
1220 

Bourne shell, see sh 
Bourne-again shell, see bash 
brace expansion, 19 
break (shell command), 35 
brk, 746 

browsers, lynx, 306-309 
commands, 308-309 
options, 306-308 

brushtopbm, 57 

bsearch() function, 900-901 
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buffchan, 1264-1265 

drop command, 1265 
flush command, 1265 
readmap command, 1265 

buffer-dirty-flush daemon, 
744-745 

buffering streams, 1016-1017 
buffers 

cache, committing to disk, 
869 

filesystem, flushing, 
1401-1402 

flushing from files to disk, 
756-757 
kernel log, 873 
kernel message ring, reading/ 
clearing, 872-874 
multiple, reading/writing 
data, 1003-1004 
BUG ADDRESS environ¬ 
ment variable, 529 
buildhash, 274, 279 
files, 281 

builtin (shell command), 35 
busmouse drivers, boot-time 
parameters, 1224 
bye (ftp command), 148 
byte strings 

comparing, 899-900 
copying, 900 
operations, 901 
writing zeros to, 902 
bytes 

counting (in files), 70 
swapping adjacent, 1043 

bzero() function, 901-902 

c 

c 

converting AN SI to 
Kernighan & Ritchie, 4 
functions, displaying 
headers, 455-456 
preprocessors, 81-84 
imake 264-267 
options 82-84 


string table source files/ 
headers, 314-315 
see also gcc 

C++compiler, seeg++ 
cacheflush, 746-747 

bugs, 747 
errors, 747 
return value, 747 

caches (ARP), manipulating, 
1263 

CAdose routine, 964 
cal, 58 

calendar sheets, seegcal 
C Alistopen routine, 964 
calling up systems, 88-90 
calloc() function, 976 
canonicalized absolute 
pathnames, 1004-1005 
CAopen routine, 964 
case 

bash command, 13 
ftp command, 148 

cat, 58-59 

catdose() function, 903-904 
catgets() function, 902-903 
catopen() function, 903-904 
cccp, 81-84 

copying, 84 
options, 82-84 

cd 

ftp command, 148 
shell command, 35-36 

CD-ROMs, boot-time 
parameters, 1222-1223 
cdable vars variable (bash), 
18 

CD PATH variable (bash), 16 
cdtin, 516 

see a/so tin 

cdup (ftp command), 148 
ceil() function, 904 
cfdisk, 1265-1269 

bugs, 1269 

commands, 1267-1268 
options, 1268-1269 

cfgetispeed() function, 877, 
1053 


cfgetospeed() function, 877, 

1052 

cfingerd, 1106-1109 

bugs, 1108 
error messages, 1108 
features, 1107-1108 
options, 1106-1107 
SYSLOG messages, 1108 
text commands, 1115 
cfingerd.conf, 1109-1115 
display files section, 
1109-1110 

finger display configure 
section, 1110-1111 
finger fake users files section, 
1114 

finger programs files section, 
1114 

finger strings configure 
section, 1113 
forwarded host section, 

1112 

internal config configure 
section, 1111-1112 
internal strings configure 
section, 1113 
rejected host section, 1112 
services header configure 
section, 1114 

services positions configure 
section, 1114-1115 
signal strings configure 
section, 1113-1114 
system list sites configure 
section, 1112 
trusted host section, 1112 
cfmakeraw() function, 1052 
cfsetispeed() function, 877, 

1053 

cfsetospeed() function, 877, 

1052-1053 

character sets, 1064-1066 

ASCII, 1064,1214-1216 
ISO 2022,1066 
ISO 4873,1066 
ISO 8859,1064-1065 
ISO 8859-1,1239-1242 
alphabets 1240 
characters 1240-1242 
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K0I8-R, 1065 
Unicode, 1065,1253-1255 
combining characters 
1254 

implementation levels 
1254 

character special files, 
creating, 325 
characters 

classifying, 957-958 
converting 
to ASCII, 1055 
wide to multi byte, 
1061-1062 

locating in strings, 953, 
1029 

multibyte, converting to 
wide characters, 978 
outputting, 997-999 
returning number of bytes 
in, 977 

searching strings for sets, 
1035-1039 
translating/deleting, 
536-539 

chat, 727-730,1269-1273 

abort strings, 1270-1271 
Boolean options, 729 
daemons, 727 
escape menu, 728 
escape sequences, 
1271-1272 
options, 1269-1270 
readdressing, 729 
report strings, 1271 
runtime options, 728-729 
script, 1270 
startup file, 729 
termination codes, 1272 
time-out value, 1271 
username field, 727 
Xll interface, 730 
chattr, 59-60 
chdir, 747-748 
checkout (cvs command), 
96-97 

checksums, computing on 
files, 501 



chfn, 60 
chgrp, 61 

child processes, creating, 751, 
758 

chkdupexe, 61 

chmod, 61-62,148,748-749 

errors, 749 
operators, 62 
options, 62 
return value, 748 
specifying mode, 748 
chooser (xdm), 607 
chown, 62-63, 749-750 
errors, 749-750 
options, 63 

chroot, 750-751,1273 

errors, 750-751 
return value, 750 

chsh, 63 
ci, 64-69 

controlling file access, 67 
diagnostics, 68 
environment, 68 
file modes, 67 
options, 65-66 
setuid privileges, 67-68 
specifying files, 66-67 
temporary files, 67 
cidentd, 69-70 
cksum, 70 
clear, 70-71 

dear-saved-lines() action 
(xterm), 715 

dearerr function, 919-920 
clearing terminal screen, 
70-71 

dientlib, 904-905 
clients 

listing running applications, 
669-670 

Remote Start, see rstart 
X, killing, 666-667 

clipboards, X client, 595-597 

buttons, 596 

sending/retrieving contents, 
596-597 


clock, 344,1273-1274 

colors, 344 
options, 1273 
xdock, 593-595 

dock() function, 905 
clocks 

alarm, setting, 744 
CMOS, 1273-1274 
kernel, adjusting, 742-743 

clone, 751 
close, 752 

ftp command, 148 
telnet command, 508 

dosedirf) function, 905-906 
doselogf) function, 
1045-1046 

C loseO nExec routine, 965 
CM OS clock, 1273-1274 
C M U bitmaps; converting to 
portable, 71 
cmuwmtopbm, 71 
co, 71-75 

diagnostics, 75 
environment, 75 
file modes, 75 

keyword substitution, 74-75 
limitations, 75 
options, 72-74 

col, 76 
colcrt, 77 

color, bitmap application, 56 
colrm, 77-78 
column, 78 
columns 

formatting lists into, 78 
removing from files, 77-78 

comm, 78-79 

options, 79 

command (shell command), 
36 

command-line options, 
parsing, 937-940 
command oriented history 
variable (bash), 17 
commands 

bitmap application 
drawing, 51-53 
Edit menu, 53-54 
File menu, 53 
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building/executing from 
standard input, 586-587 
cu, 88-89 
cvs, 91-104 
editres, 121-122 
execution, bash, 25 
exit status, 26 
ftp, 148-152 
gpic, 212-213 
history lists, displaying, 39 
info, 269-270 
ispell, 274-275 
locating sourc^binary and 
manuals files, 575-576 
Ipc, 1317-1318 
lynx, 308-309 
more, 328 

nslookup, 1351-1353 
options, parsing, 207-208 
RCS, 447-449 
readline library, 29-32 
redirection, 21-23 

duplicating file descriptors 
23 

here-documents 22-23 
input, 22 

opening file descriptors 23 
operators 21 
output, 22 

standard error output, 22 
standard output, 22 
remote execution, 569-571 
sed, 478-479 
grouping, 478 
syntax, 476 
shell (built-in), 35-45 
enabling/disabling, 37 
help information, 38 
telnet, 508-512 
tftp, 514 
timedc, 1409 
tin 

article viewer, 522-524 
editing, 519 

global options menu, 524- 
525 

group index, 521-522 


newsgroup selection, 
519-520 

Soool directory selection, 
520 

thread listing, 522 
top, 534-535 
xauth, 588, 591 
zmore, 733-734 

comment-begin variable 
(readline), 28 
comments 

bash, 14 
sed, 477 

commit (cvs command), 

96-98 

comparing 

files, 78-79 

compressed, 731-732 
strings, 1029-1030 
ignoring case, 1028 
using current locale 1030 
compilers 

g++, 155-160,174-201 
bugs 160 
copying, 160, 201 
filename suffixes 174-175 
files 159-160, 200 
options 155-159, 
175-178 

pragmas 159, 200 
gcc, 174-201 

assembling output, 8-9 
bugs 201 
copying, 201 

filename suffixes 174-175 
files 200 
options 175-178 
pragmas 200 
rpcgen, 464-466 
compiling, make utility 
(recompiling programs), 
310-312 

completion-query-items 
variable (readline), 28 
compound commands (bash), 


compressed files 

comparing, 731-732 
compressing/expanding, 
248-252 

executable files 252-253 
searching for regular 
expressions, 733 
viewing text, 733-734 

comsat, 1274-1275 

concatenating 

files, 58-59 
compressed, 251 
portable anymaps, 383 
strings, 1028-1029 

C oncurrent Versions System, 
see cvs 

conditional expressions, 
evaluating, 43 

configurable fi nger daemon, 
1106-1109 

configuration file, 
1109-1115 
display files section, 
1109-1110 

finger display configure 
section, 1110-1111 
finger fake users files 
section, 1114 
finger programs files 
section, 1114 
finger strings configure 
section, 1113 
forwarded host section, 
1112 

internal config configure 
section, 1111-1112 
internal stringsconfigure 
section, 1113 
rq'ected host section, 1112 
services header configure 
section, 1114 

services positions configure 
section, 1114-1115 
s'gnal stringsconfigure 
section, 1113-1114 
system liststesconfigure 
section, 1112 
trusted host secti on, 1112 
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error messages, 1108 
features, 1107-1108 
SYSLOG messages, 1108 

configuration information, 
getting at runtime, 
1043-1045 
configuring 

network interfaces, 
1304-1305 
rstartd, 469 
keywords, 470 
serial ports, 1394-1395 
SF86_SVGA servers, 
627-628 

SF86_VGA16 servers, 631 
system logging file, 
1402-1403 
tinrc, 525-526 
XF86_Accel servers, 

615-616 

XF86_M ono servers, 624 
XFree86, 636 
xfs, 642 

xinetd, 656-660 

confstrf) function, 906-907 
connect, 752-753 
connections 

dialup IP, handler, 
1285-1288 

displaying active, 1339-1342 
routing information, 1341 
secket information, 
1340-1341 

displaying active routing 
information, 1341 
full-duplex, shutting down, 
855 
socket 

accepting, 740-741 
initiating, 752-753 
listening for, 792-793 

console, 1066-1067 
console_ codes, 1067-1074 

character sets, 1072 
control characters, 1068 
CSI sequences, 1069-1070, 
1074 



display attributes, 
1070-1071 

ESC sequences, 1068-1069, 
1073-1074 
mode switches, 1071 
mouse tracking, 1072-1073 
private CSI sequences, 1072 
Set/Reset M ode sequences, 
1071 

status report commands, 
1071 

consoleioctls, 1074-1080 
consoles 

control-character handling, 
1073 

properties, 1067 
sequences, 1067-1074 
character sets 1072 
control characters 1068 
CSI, 1069-1070, 1074 
di^lay attributes 
1070-1071 
ESC, 1068-1069, 
1073-1074 
mode snitches 1071 
mouse tracking, 
1072-1073 
private CSI, 1072 
Set/Reset M ode 1071 
Status report commands 
1071 

starting processes on, 1066 
switching, 1067 
virtual, 1066 

memory, 1101-1102 

continue (shell command), 36 
control messages, 1310 
control operators (bash), 12 
control statements, awk, 167 
control.ctl, 1115-1116 
controlling terminal, getting 
name, 909 
convdate, 79 

conversational exchanges, 
1269-1273 

abort strings, 1270-1271 
chat script, 1270 
escape sequences, 

1271-1272 


report strings, 1271 
termination codes, 1272 
time-out value, 1271 
convert-meta variable 
(readline), 28 
converting 

Abekas YU V bytes to 
portable pixmaps, 731 
Andrew T oolkit raster 
objects to portable 
bitmaps, 10 

AN SI C to Kernighan & 
RitchieC, 4 

ASCII graphics to portable 
graymap, 10 
Atari files 

compressed Spectrum files 
to portable pixmaps 494 
DegasPII files to portable 
pixmaps 378 
D egasPI3 files to portable 
bitmaps 379 
uncompressed Spectrum 
files to portable pixmaps, 
495-496 

AutoCAD slide files to 
portable pixmaps, 490-491 
Bennet Yee face files to 
portable bitmaps, 726 
Biorad confocal files to 
portable graymaps, 48-49 
bitmap files, 49 
CM U to portable 71 
to portable pixmaps 57 
characters 

to ASCII, 1055 
wide to multi byte 
1061-1062 
dates/times, 79 
to ASCII, 984-986 
to D iseordian format, 
1210-1211 

documents, troff to LaTeX, 
1252-1253 
doodle brush files to 
portable bitmaps, 57 
FITS files to portable 
anymaps, 142-143 
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fonts 

Bitmap D istribution 
Format to Portable 
Compiled Format, 47 
packed format to portable 
bitmaps 381 

GEM IMG files to portable 
bitmaps, 201 
GIF files to portable 
anymaps, 208-209 
Gould scanner files to 
portable pixmaps, 211 
groff output toTeX dvi 
format, 227-228 
G roup 3 fax files to portable 
bitmaps, 160-161 
HIPS files to portable 
graymaps, 256 
H P PaintJ et files to portable 
pixmaps, 381 
ILBM files to portable 
pixmaps, 263-264 
image file to portable 
anymap, 4 
I mg-whatnot files to 
portable pixmaps, 267 
letters 

totowerca se 1055-1056 
toupperca se, 1055-1056 
Lisp machine bitmap files to 
portable graymaps, 292 
M acintosh PICT files to 
portable pixmaps, 379-380 
M acPaint files to portable 
bitmaps, 309-310 
MGR bitmaps to portable 
bitmaps, 322-323 
multibyte characters to wide 
characters, 978 
multibyte strings to wide 
character, 977-978 
object code into N LM 
outfiles, 338-339 
PCX files to portable 
pixmaps, 368-369 
Photo-CD files to portable 
pixmaps, 260-261 


portable anymaps 
toDDIF format, 396 
to FITS format, 396-397 
to PostScript, 397 
to SGI image file 
398-399 

to Solitaire format, 399 
to Sun raster files 398 
toTIFF files, 399-400 
intoXll window dumps 
400 

portable bitmaps 

to Andrew Toolkit raster 
objects 358 
to ASCII graphics 357 
to Atari Degas PI 3 files, 
364 

to BennetYee “face" files 
367 

to BitGraph graphics 358 
to CM U window manager 
bitmaps 358-359 
to compressed G raphO n 
graphics 360-361 
to DEC LN 03+Sixel 
output, 362 

to encapsulated PostScript- 
stylebitmaps 359 
to Epson printer graphics 
359 

to GEM IMG files 360 
to Gemini 1 Ox graphics 
356 

to Group 3 fax files 360 
to HP LaserJet format, 
361-362 

to M acPaint files 363 
toM GR bitmap, 363 
to packed format fonts 

364- 365 

to portable graymaps 364 
to PostScript, 362 
to Printronix printer 
graphics 366 
to Sun icons 361 
to UN IX plot files 

365- 366 


toXlO bitmaps 366 
toXll bitmaps 367 
to Zinc bitmaps 367-368 
portable graymaps 
to L iso machine format, 
376-377 

to portable bitmaps 377 
to portable pixmaps 378 
toUsenixFaceSaver 
format, 376 
portable pixmaps 

to Abekas YU V files, 428 
to Atari DegasPIl files, 
422 

to AutoCAD, 414-416 
to BMP files 416 
to DEC axel format, 
425-426 

to GIF files 416-417 
to HP PaintJet files 423 
to HP PaintJet XL PCL 
files, 424 

to ILBM files 418-419 
to M acintosh PICT files 
422-423 

to M itsubishi S340-10 
files, 420-421 
toMotifUIL icon files 
427 

to NCSA ICR format, 
417-418 
to PCX files 421 
to portable graymaps 
421-422 

to red/blue 3D glasses 
400-401 

to three portable graymaps 

425 

to three raw YU V files 
428-429 

to Tru$/ision Targa files 

426 

toXll pixmaps 427-428 
toXll puzzle files, 
424-425 

PostScript files to portable 
anymaps, 434-435 
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PostScript image data to 
portable graymap, 

433-434 

QRT ray tracer output to 
portable pixmaps, 436-437 
raw grayscale bytes to 
portable graymaps, 439 
raw RG B bytes to portable 
pixmaps, 439-440 
ray tracer output to portable 
pixmaps, 333 

SGI image files to portable 
anymaps, 483-484 
Solitaire files to portable 
anymaps, 488-489 
spaces to tabs, 559 
SPOT satellite images to 
portable graymaps, 495 
strings 

ASCII to double 
1039-1040 
to long integers 1041 
to unagned long integers 
1041-1042 
wide character to 
mu Itibyte character, 

1061 

Sun icons to portable 
bitmaps, 262 

Sun raster files to portable 
anymaps, 438 
tabs to spaces, 137 
TIFF files to portable 
anymaps, 515-516 
times 

initializing information, 
1058-1060 
to ASCII, 984-986 
to tm structure, 1036- 
1037 

T rueVision T arga files to 
portable pixmaps, 515 
Usenet batch files to IN N 
format, 1281-1282 
Usenix FaceSaver files to 
portable graymaps, 147 



Xll or X10 bitmaps to 
portable, 592 
Xll pixmaps to portable, 
677 

X11/X10 window dump 
files to portable anymaps, 
722 

Xconfig fileformat to 
XF86Config, 454 
XIM files to portable 
pixmaps, 654 
XV thumbnail pictures to 
portable pixmaps, 720 
YU V files to portable 
pixmaps, 730-731 
convolution kernels, generat¬ 
ing, 372-373 
cookies, generating, 317 
copying 
ar utility, 7 
as, 9 

byte strings, 900 
files, 80-81 

converting while, 108-109 
install, 272-273 
MS-DOS to/from UNIX, 
317-318 
U N IX-to-U NIX, 

563-565 

M S-D OS files to U NIX, 

329 

number signs, 907 
strings, 1030-1031 
stpcpyf) function, 
1027-1028 

copysignf) function, 907 
cos() function, 907 
cosh() function, 908 
cosines, 907 
cp, 80-81 
cpp, 81-84 
copying, 84 
options, 82-84 
CPU, listing most intensive 
processes, 533-535 
cr (ftp command), 148 
creat, 815-816 


create_ module, 800-802 
crond, 1275 
crontab, 84-85 
crypt function, 908-909 
csplit, 85-86 
ctags, 87-88,135-137 
bugs, 88 

copying, 136-137 
files, 87 

options, 87,136 

ctermid() function, 909 
ctime, 909-910, 984-986 
ctlinnd, 1276-1279 

bugs, 1279 

commands, 1276-1278 

Ctrl+Alt+Del combination, 
setting function, 1279 
ctrlaltdel, 1425 
ctrlaltdel, 1279 
cu, 88-90 
bugs, 90 

commands, 88-89 
options, 89-90 

cuserid() function, 934-935 

bugs, 935 
errors, 934 
files, 935 

cut, 90-91 

cut buffers, copying selections 
into, 598-599 
cvs, 91-106,1116-1120 

commands, 91-104 
add, 96 
admin, 96 
checkout, 96-97 
commit, 96-98 
diff, 98 
export, 98 
history, 99 
import, 100 
log, 100 
rdiff, 101 
relea se 101 
remove, 101-102 
rtag, 102 
status 102 
tag, 102-103 
update 103-104 
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environment variables, 

105-106 

CVS_IGNORE_REMOTE 
_ROOT, 105 
CVS_RSH, 106 
CVSJERVER, 106 
CVSEDITOR, 105 
CVSREAD,105 
CVSROOT, 105 
CVSWRAPPERS, 106 
RCSBIN, 105 
files, 104-105,1117-1119 
options, 92-104 

checkout command, 97 
commit command, 97 
history command, 99 
import command, 100 
rdiff command, 101 
sending problem reports, 

1279- 1281 
filling out reports 

1280-1281 
startup file, 93 
support files, 1116-1120 
CVSIGNOREREMOTE 
ROOT environment 
variable, 105 
CVS RSH environment 
variable, 106 

CVS SERVER environment 
variable, 106 
cvsbug, 1279-1281 

EM ACS interface, 1281 
environment, 1280 
files, 1281 
filling out reports, 

1280- 1281 
options, 1280 

CVSEDITOR environment 
variable, 105 
CVSREAD environment 
variable, 105 
CVSROOT environment 
variable, 105 

CVSWRAPPERS environment 
variable, 106 


cvt batch, 1281-1282 
C ydades drivers, tuning, 
1282-1284 
cytune, 1282-1284 

bugs, 1283 
options, 1283 

D 

daemons 

buffer-dirty-flush, 744-745 
configurablefinger daemon, 
1106-1109 
configuration file 
1109-1115 
error messages 1108 
features 1107-1108 
SYSLOG messages 1108 
cron, 1275 

I nterN etN ews, 1309-1312 
control messages 1310 
controling, 1276-1279 
kernel log, 1315-1317 
line printer spooler, 
1318-1320 

network routing, 1380-1382 
NFS mount, 1332-1333 
N FS service, 1347 
powerd, 1359-1360 
pppd,1360-1369 
timeserver, 1407-1408 
UUCP file transfer, 
1415-1417 
DARPA 

FTP server, 1301-1304 
requestssupported, 
1302-1303 

port numbers, converting 
PRC program numbers to, 
1358-1359 

Telnet server, 1406-1407 
T FT P server, 1407 

data buffers, flushing from 
files to disk, 756-757 
data cache, flushing contents, 
746-747 

data segments, changing, 746 


databases 

bibliographic, 219 
fields 219 

inverted indexes 209-210 
searching, 210, 292-293 
filename, updating, 561-562 
files, searching for patterns, 
295 

news overview 
e<piring entries 
1293-1294 
format, 1168-1169 
updating, 1353-1354 
ps, updating, 436 
rebuilding for mail aliases 
file, 336 

RGB colorname, 
uncompiling, 488 
terminal capability, 

1188-1197 

boolean capabilities 1189 
numeric capabilities 

1189- 1190 
string capabilities 

1190- 1197 

U senet, recovering, 1342- 
1344 

date, 106-108 

arguments, 106-107 
files, 108 
options, 108 
dates/times 
converting, 79 
to ASCII, 909-911, 
984-986 

to D iscordian format, 
1210-1211 
strings to numbers 
989-990 

formatting, strftimef) 
function, 1032-1034 
returning current, 928-929 
setting, 107-108 
showing, 106-107 
dd, 108-109 
ddate, 1210-1211 
D D check routine, 965 
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D Dend routine, 965 
DD start routine, 965 
debug (ftp command), 149 
debugfs, 1284-1285 

commands, 1284-1285 
options, 1284 

declare (shell command), 36 
deltimer, 1424 
delete_module, 800-802 
delete (ftp command), 148 
deleting 

binary tree items, 1056 
directories, 829-830 
M S-D OS directory trees, 
319 

MS-DOS files, 318-319 

depmod, 109-112 

configuration, 110-111 
files, 111 
strategy, 111 

descriptor tables, size 
(getting), 760-761 
descriptors, testing, 958-959 
/dev directory, 1236 
devices 

bad blocks (searching for), 
1264 

controlling, 774-788 
ioctl cal Is (list of), 

775-786 

creating, 815-816, 
1321-1324 

describing all, 1120-1121 
disk, ram, 1094-1095 
DOS (tableof), 1152-1158 
Ethernet, boot-time 
parameters, 1223 
floppy disk, 1080-1083 
configuration, 1080-1082 
hard disk, 1083 
line printer (ioctl() calls), 
1090-1091 

Ip, parameters (setting), 
1413-1414 
opening, 815-816 
PLIP, tuning parameters, 
1357 



SCSI tape, drivers, 
1096-1100 
setup, 849 
swapping 

enabling/disabling, 1401 
starting/stopping, 866-867 
terminal (list of), 1197 

DEVINFO, 1120-1121 
df, 112-113 

dialup IP connection handler, 
1285-1288 

dialin mode, 1286-1287 
dialout mode, 1287-1288 

dictionaries, compressing/ 
uncompressing, 496 
diff (cvs command), 98 
difftime, 911, 984-986 
dig, 113-117 
bugs, 117 
environment, 117 
files, 117 
options, 114-115 
dip, 1285-1288 

command mode, 1285-1286 
dialin mode, 1286-1287 
dialout mode, 1287-1288 
files, 1288 
dir, 303-304 
bugs, 304 
ftp command, 149 
options, 303-304 
directories 
/, 1236 

adding to stack, 40 
alphabetizing entries, 
1012-1013 
/ bin, 1236 
/boot, 1236 

changing, 35-36, 747-748 
closing, 905-906 
creating, 323 
mkdir, 794-795 
mknod, 795-796 
deleting, 829-830 
/dev, 1236 
displaying list of, 36 
/d os, 1236 


/etc, 1236 
/etc/skel, 1236 
/etc/Xll, 1236 
files (searching for), 137-142 
getting current, 931 
getting entries, 759 
filesystem-independent 
format, 931-932 
hierarchies, creating, 323 
/home, 1236 
/lib, 1236 

listing contents, 303-304 
/mnt, 1236 
MS-DOS 

changing, 316-317 
diplaying, 319 
opening, opendir, 989 
printing pathnames, 40 
/proc, 1236 
promoting, 39-40 
RCS, creating, 447-449 
reading 
entries 823 
readdirf) function, 
1002-1003 
removing, 462 
root, changing, 750-751, 
1273 

/ sbin, 1237 
scanning for matching 
entries, 1012-1013 
stream, resetting, 1011 
/tmp, 1237 

trees, walking through, 930 
/usr, 1237 
/usr/X 11R6,1237 
/usr/X llR6/bin, 1237 
/usr/X 11R6/Iib, 1237 
/usr/X 11R6/Iib/X 11,1237 
/usrXHR6/indude/Xll, 
1237 

directory stream, current 
location (returning), 1048 
directory trees 

M S-D OS, deleting, 319 
shadow directories 
(creating), 294 
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dirs (shell command), 36 
disconnect (ftp command), 
149 

D iscordian dates (converting 
to), 1210-1211 
disks 

adding M S-DOS filesystems 
to, 321-322 

devices, ram, 1094-1095 
displaying usag^limits, 437 
floppy 

formatting, 1295-1296 
marking bad blocks 316 
setting parameters 1391 
M S-D OS, mounting, 
326-327 

quotas, manipulating, 
821-822 

SCSI, drivers, 1095-1096 
summarizing free space, 
112-113 

summarizing usage, 120-121 
Xdf, 332 

display argument command 
(telnet), 508 

DISTRIBUTION environ¬ 
ment variable, 529 
div() function, 911 
dividing integers, 911 

floating-point remainders, 
913, 923 

returning quotient and 
remainder, 961 

dmesg, 1288-1289 
dncomp, 1008-1011 
dnexpand, 1008-1011 
dnsdomainname, 259-260 
dnsquery, 117-119 
bugs, 119 
diagnostics, 118 
files, 118 
options, 117-118 
documents 

converting, troff to LaTeX, 
1252-1253 

formatting, gtroff, 237-248 


dollar signs ($) 

bash special parameters, 15 
expansion, 19 
ftp command, 148 
domain names 
current host, 119 
displaying, 259-260 
getting/setting, 760 
querying servers, 117-119 
sending query packets to 
servers, 113-117 
servers, resolver routines, 
1008-1011 

domain servers, looking up 
hostnames with, 257-258 
domainname, 119 
domains, nameserver, 
1334-1338 
querying, 1350-1353 
doodle brush files, converting 
to portable bitmaps, 57 
DOS devices, table of, 
1152-1158 
/dos directory, 1236 
drand48() functions, 912 
drawing bitmaps (commands), 
51-53 

drem() function, 913 
drivers 

busmouse, boot-time 
parameters, 1224 
Cyclades, tuning, 

1282-1284 

floppy disk, boot-time 
parameters, 1223-1224 
SCSI disks, 1095-1096 
SCSI tape devices, 
1096-1100 

ioctlf) calls 1097-1100 
sound, boot-time param¬ 
eters, 1224 

d split, 119-120 
du, 120-121 
dumpe2fs, 1289 
dumping files, 345-346 
dup, 753-754 


dup2, 753-754 

duplicate executables, finding, 
61 

duplicating strings, 1031 

E 

e-mail 

notification, 48 
sending, 1387-1390 
aliases 1390 

e2fsck, 1289-1291 

bugs, 1291 
exit code, 1290 
options, 1290 

echo (shell command), 36-37 
ECHO_REQUEST packets, 
sending, 1358 
ecvt() function, 913-914 
Edit menu commands, bitmap 
application, 53-54 
editing bitmaps, 49-51 
editing-mode variable 
(readline), 28 
editors 

emacs, 130-133 
bugs 133 
distributing, 133 
fils, 132-133 
manuals 132 
moussbutton bindings 
132 

options 130 
X Window System, 
131-132 

stream-oriented, seesed 
editres, 121-126 

beginning sessions, 121 
blocking requests, 124 
commands, 121-122 
environment, 126 
files, 126 
options, 121 
resource box, 123-124 
resources, 124-125 
widgets, 125-126 
window, 121 
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edquota, 1291-1292 
egrep, 224-226 

bugs, 226 
diagnostics, 226 
options, 224-225 
regular expressions, 225-226 

$else parser directive 
(readline), 29 
elvis, 126-128 

bugs, 128 

environment, 127-128 
files, 127 
options, 127 
ref interaction, 455 
tag files, 135-137 
elvprsv, 128-129 
elvrec, 129-130 
emacs, 130-133 
bugs, 133 
distributing, 133 
files, 132-133 

function key/mouse support, 
134-135 
manuals, 132 

mouse button bindings, 132 
options, 130 
tag files, 135-137 
using emacstool with, 135 
X W indow System, 131-132 
E M AC S user i nterface, 
cvsbug, 1281 
emacstool, 134-135 
bugs, 135 

environment variables, 135 
files, 135 
options, 134 
using with emacs, 135 

enable (shell command), 37 
encoded files, uuencode 
format, 1200 
encryption 

crypt function, 908-909 
memory areas, 980-981 

endgrent() function, 932-933 
$endif parser directive 
(readline), 29 



endmntent() function, 

935- 936 

endnetent subroutine, 

936- 937 

endprotoent() function, 
941-942 

endpwent() function, 943 
endservent() function, 946 
endusershell() function, 
946-947 

endutent() function, 947 
ENV variable (bash), 16 
environ, 1121 
environ command (telnet), 
511 

environment variables 

adding/changing, 996-997, 
1017 

bash, 25-26 
ci, 68 
co, 75 

cvs, 105-106 
CVSJGN ORE 
_REM OTE_ROOT, 
105 

CVS_RSH, 106 
CVSJERVER, 106 
CVSEDITOR, 105 
CVSREAD, 105 
CVSROOT, 105 
CVSW RAPPERS, 106 
RCSBIN, 105 
cvsbug, 1280 
dig, 117 
editres, 126 
elvis, 127-128 
emacstool, 135 
fsinfo, 145 
fslsfonts, 146 
fstobdf, 146 
ftp, 154 
gawk, 172 

getopt() function, 939 
getting, 932 
groff, 229 
gtroff, 248 
gzip, 251 


imake, 267 
info, 270 
Id, 291 
Ikbib, 293 
locate, 295 

l pq, 299 

l pr, 300 
Iprm, 302 
more, 328 
nslookup, 1353 
res, 443 
rcsclean, 444 
resdiff, 445 
resmerge, 450 
ref, 455 

rlog, 459 
rlogin, 461 
script, 475 
startx, 497 
teal, 506 
telnet, 512 
tin, 528-530 

ADD_AD DRESS, 529 
AUTOSUBSCRIBE, 529 
AUTOUNSUBSCRIBE, 
530 

BUG_ADDRESS, 529 
DISTRIBUTION, 529 
MAILER, 529 
NNTPSERVER, 529 
ORGANIZATION, 529 
REPLYTO, 529 
TI_ACTIVEFILE, 529 
TI_NOVROOTDIR, 529 
TIN_HOMEDIR, 528 
TIN JNDEXDIR, 529 
TIN_LIBDIR, 529 
TINJPOOLDIR, 529 
TINRC, 528 
VISUAL, 529 
tset, 541 
twm, 557 
TZ, 987 
ul, 559 

xauth, 589, 592 
xdipboard, 597 
xdock, 595 
xcmsdb, 593 
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xconsole, 598 
xdm, 608 
XFree86, 637 
xhost, 644 
xinit, 666 
xlogo, 668 
xlsatoms, 669 
xlsclients, 669 
xlsfonts, 671 
xmodmap, 675 
xprop, 680 
xrdb, 684 
xrefresh, 685 
xstdcmap, 700 
xterm, 717 
xwd, 722 
xwininfo, 724 
xwud, 726 
eqn, seegeqn 

equation formatting, 202-206 
erand48() functions, 912 
erf() function, 914 
erfc() function, 914 
errno, 916-917 
error functions, 914 
errors 

access, 741 
adjtimex, 743 
bdflush, 745 
bind, 745-746 
cacheflush, 747 
chdir/fchdir, 747-748 
chmod, 749 
chown, 749-750 
chroot, 750-751 
clone, 751 
close, 752 

codes, describing (returning 
strings), 1032 
creat, 816 
dup/dup2, 753 
execve, 754 
fchmod, 749 
fchown, 749-750 
fcntl, 756 
fdatasync, 757 
fork/vfork, 758 


fsync, 759 

getdents, 759 

getdomainname, 760 

getgroups, 762 

gethostname, 763 

getitimer, 764 

getpeername, 765 

getpriority, 766-767 

getrlimit, 768 

getsid, 768 

getsockname, 769 

getsockopt, 771 

gettimeofday, 773 

idle, 774 

ioctl, 774 

iopl, 789 

kill, 790 

killpg, 791 

link, 791-792 

listen, 792 

llseek, 793 

Iseek, 794 

mkdir, 795 

mknod, 796 

mlockall, 798 

mmap, 799 

modifyjdt, 800 

mount, 803 

mprotect, 804 

mremap, 806 

msgctl, 807 

msgget, 808 

msgop, 810 

munlock, 812 

munmap, 799 

mysnc, 811 

nanosleep, 813 

nice, 814 

open, 816 

pause, 817 

personality, 818 

return value, 797 

returning number, 916-917 

setdomainname, 760 

setgroups, 762 

sethostname, 763 

setitimer, 764 


setpriority, 766-767 
setrlimit, 768 
setsockopt, 771 
settimeofday, 773 
symbolic error names, 
916-917 
unmount, 803 
escape character, bash, 14 
etags, 135-137 
copying, 136-137 
options, 136 
/etc directory, 1236 
/etc/modules file, 1152 
/etc/skel directory, 1236 
/etc/Xll directory, 1236 
Ethernet devices, boot-time 
parameters, 1223 
Euclidean distance (finding), 
953 

EU ID variable (bash), 15 
eval (shell command), 37 
event timers, managing, 1424 
ex, seeelvis 
exclamation points (!) 
bash special parameters, 15 
ftp command, 148 
exec (shell command), 37 
execl function, 914-916 
execle function, 914-916 
execlp function, 914-916 
exect function, 914-916 
executable files, compressing/ 
expanding, 252-253 
executables, duplicate 
(finding), 61 

executing programs, 754-755 
pausing, 813-814 
suspending, 1061 
execv function, 914-916 
execve, 754-755 
execvp function, 914-916 
exit, 739-740, 917 
shell command, 37 
xauth, 591 

exit status (commands), 26 
exp() function, 918 
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expand, 137 
expand-tilde variable 
(readline), 28 

expanding files, see compress¬ 
ing/expanding files 
expansion, 18-21 

arithmetic, 20 
brace, 19 

command substitution, 20 
history, 33-34 

event designators 33 
modifiers 34 
word designators 33 
parameter, 19-20 
pathname, 21 
process substitution, 20 
quote removal, 21 
tilde, 19 

word splitting, 21 

expire, 1292-1293 
expire.ctl, 1121-1123 
expireover, 1293-1294 
expml() function, 918 
exponents; 918 
export 

cvs command, 98 
shell command, 37 

exported kernel symbols, 
displaying, 284-285 
exports, 1123-1125 

files, 1124 
options, 1123 
user ID mapping, 
1123-1124 

expressions 

conditional, evaluating, 43 
find, 138 
gawk, 166 
gpic, 213-214 
grep, 225-226 
label, grefer, 223-224 
numeric, gtroff, 239 
regular, sed, 476-477 
ext filesystem, 1125 
ext2 filesystem, 1125 
extracting from archives, 5-7 



F 


fabs() function, 919 
face files, converting to 
portable bitmaps, 726 
fastrm, 1294-1295 
fc (shell command), 37-38 
FCEDIT variable (bash), 17 
fchdir, 747-748 
fchmod, 748-749 
fchown, 749-750 
fdose function, 919 
fcntl, 755-756 
fcvt() function, 913-914 
fd, 1080-1083 

configuration, 1080-1082 
ioctl() calls supported, 1082 
FDCLR macro, 836 
FD ISSET macro, 836 
FD SET macro, 836 
FDZERO macro, 836 
fdatasync, 756-757 
fdformat, 1295-1296 
fdisk, 1296-1297 
fdopen function, 924-925 
feof function, 919-920 
terror function, 919-920 
fflush function, 920-921 
ffs() function, 921 
fg (shell command), 38 
fgetc() function, 945 
fgetgrent() function, 921-922 
fgetpos function, 927-928 
fgetpwent() function, 

922-923 

fgets() function, 945 
fgrep, 224-226 

bugs, 226 
diagnostics, 226 
options, 224-225 
regular expressions, 225-226 

fields, awk, 163 

FIFOs (named pipes), 1403 

creating, 323-325, 982-983 
system logging, 1403 

FIGNORE variable (bash), 17 


file descriptors 

duplicating, 23 
manipulating sets, 836 
opening, 23 
reading from, 822 
writing to, 889-890 
File menu commands, bitmap 
application, 53 
file table 

adding entries, 1428-1429 
description, 1425-1426 
initializing, 1427 
moving files to end, 1431 
removing files, 1431-1432 
structure, 1426 
table entries, 1426 
unreferenced entries, 
fetching, 1428 

file-creation mask, setting, 45 
file, table, 1425-1426 

table entries, 1426 
table structure, 1426 

file table init, 1427 
filechan, 1297-1298 
filename databases, updating, 
561-562 
filenames 
matching, 924 
temporary, creating, 
983-984 

fileno function, 919-920 
files 

aborting transfer, 152 
access permissions, 
changing, 61-62 
agetty, 1261 
Atari 

compressed Spectrum, 
converting to portable 
pixmaps 494 
DegasPII, converting to 
portable pixmaps 378 
Degas PI 3, converting to 
portable bitmaps, 379 
uncompressed Spectrum, 
converting to portable 
pixmaps 495-496 
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attributes, 59 

changing (second extended 
filesystem), 59-60 
authority (X), xauth file 
utility, 587-592 
AutoCAD slide, converting 
to portable pixmaps, 
490-491 
bash, 46 
binary 

encoding/decoding, 

565-566 

locating for commands 
575-576 

Biorad confocal, converting 
to portable graymaps, 
48-49 

bitmap, converting, 49 
to portable pixmaps 57 
block special, creating, 325 
character special, creating, 
325 

comparing, 78-79 
compressed 

comparing, 731-732 
searching for regular 
expressions 733 
viewing text, 733-734 
compressing/expanding, 
248-252 

concatenation, 251 
executable files 252-253 
computing checksums, 501 
concatenating, 58-59 
configuration values, getting, 
925-926 
copying, 80-81 
between machines, 
440-441 

converting while 108-109 
install, 272-273 
counting bytes/words/lines, 
70, 574 

creating, 815-816 
masks 880 

cuseridf) function, 935 
cutting sections from, 90-91 


cvs, 104-105,1117-1119 
startup, 93 
cvsbug, 1281 
database, searching for 
patterns, 295 
date, 108 
descriptors 
dosing, 752 
duplicating, 753-754 
manipulating, 755-756 
domainname, 119 
doodle brush, converting to 
portable bitmaps, 57 
dumping, 345-346 
/etc/modules, 1152 
executing, 914-916 
exports, 1124 

face, converting to portable 
bitmaps, 726 
filesystem description, 
accessing, 935-936 
filters, hexdump, 254-256 
FITS, converting to portable 
anymaps, 142-143 
font, 1128 

adding font-metric 
information, 2 
creating, 3 

groff (creating for), 513 
formats, converting Xconfig 
to XF86Config, 454 
free, 144 

gcc/g++, 159-160, 200 
GEM IMG, converting to 
portable bitmaps, 201 
GIF, converting to portable 
anymaps, 208-209 
Gould scanner, converting 
to portable pixmaps, 211 
group, getting entries, 
921-922, 932-934 
group ownership, changing, 
61 

gtroff, 248 

gzip, forcing .gz extension, 
732-733 


FI IPS, converting to 
portable graymaps, 256 
FI P PaintJet, converting to 
portable pixmaps, 381 
httpd, 261 

identifying processes, 154- 
155 

identifying RCS keyword 
strings in, 262-263 
ifconfig, 1305 
ILBM, converting to 
portable pixmaps, 263-264 
image, converting to 
portable anymap, 4 
imake, 266 

I mg-whatnot, converting to 
portable pixmaps, 267 
joining fields, 282-283 
linking, 293-294, 791-792 
Lisp machine bitmap, 
converting to portable 
graymaps, 292 
listing attributes, 304-305 
location, changing, 828-829 
lock, creating for shell 
scripts, 487 
login, 297 

login record, 1198-1200 
M acintosh PICT, convert¬ 
ing to portable pixmaps, 
379-380 

M acPaint, converting to 
portable bitmaps, 309-310 
M AKEDEV, 1321 
makefiles, creating 
dependencies in, 312-314 
man, 1248 

manual page, locating for 
commands, 575-576 
mapping/unmapping, 
799-800 
merging 
lines 347 
three-way, 320 
mesg, 321 
modprobe, 111 
mount, 1332 
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MS-DOS 

changing attribute flags 
315-316 

copying to/from UNIX, 
317-318, 329 
deleting, 318-319 
displaying contents 
333-334 

manipulating (mtoolj, 
330-333 
moving, 327 
renaming, 329-330 
mtools, testing, 330 
named, 1337 
names 

changing, 828-829 
displaying from U senet 
hittory file, 226-227 
naming conventions 153 
.netrc, 153-154 
NLM outfiles, converting 
object code into, 338-339 
nontext, printing strings 
from, 498 

numbering lines, 337-338 
object 

copying/translating, 

341-342 

discarding ymbolsfrom, 
499 

displaying information 
from, 342-343 
Using section and total 
sizes 489-490 
Using symbols from, 
339-340 

offsets, repositioning, 
793-794 

opening, 815-816 

advisory locks (applying/ 
removing), 757 
outputting 
ends of, 504 
headers 253-254 
ownership, changing, 62-63, 
749-750 


password, editing, 
1418-1419 

PCX, converting to portable 
pixmaps, 368-369 
permissions 

changing, 748-749 
checking, 741-742 
sttting modes 272-273 
Photo-CD, converting to 
portable pixmaps, 260-261 
portable anymap 
format, 1173 
reading, 971 
writing, 971-972 
portable bitmap 
format, 1170-1171 
reading, 968 
writing, 968-969 
portable graymap 
format, 1171-1172 
reading, 970 
writing, 970 
portable pixmap 
format, 1173-1174 
reading, 974 
writing, 974 

PostScript, converting to 
portable anymaps, 434- 
435 

preserving after crashes, 
128-129 

printer/plotter accounting, 
reading, 1354-1355 
printing, in reverse, 503-504 
protocol definition, 1180- 
1181 
RCS 

changing attributes 

441-443 

deaning, 443-445 
comparing re/isons 

445- 446 

controlling access 67 
format, 1181-1183 
freezing configuration, 

446- 447 
modes 67 


organization (diagram), 
1182 

printing log messages 
458-460 

retrieving re/isons 71-75 
specifying, 66-67 
Soring revisons 64-69 
temporary files 67 
recovering after crashes, 
129-130 

refs, generating, 87-88 
remote distribution, 

451-454 

removing, 461-462 
columns 77-78 
sttsof, 1294-1295 
renaming, 334-335 
resolver configuration, 
1183-1184 
reversing lines, 457 
searching for (in directories), 
137-142 

SF86Config, generating, 

633 

SGI image, converting to 
portable anymaps, 

483-484 

shar, unpacking, 560-561 
shrinking, 488 
Solitaire, converting to 
portable anymaps, 

488-489 

sorted, removing duplicate 
lines, 560 
source, locating for 
commands, 575-576 
spell-checking utilities, 281 
splitting, 85-86,119-120, 
494-495 

status, getting, 863-864 
string tableC source files/ 
headers, 314-315 
substituting definitions into, 
500-501 

suffixes, list of, 1249-1252 
Sun raster, converting to 
portable anymaps, 438 
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swapping 

enabling/disabling, 1401 
starting/stopping, 866-867 
symbolic links, 867-869 
synchronizing 

in-coredata, 756-757 
in-corestate, 758-759 
with memory maps 811 
tag 

emacs 135-137 
vi, 135-137 
tags, generating, 87-88 
temporary 

creating, 983,1053-1054 
naming, 1049,1054 
text 

converting for printing, 
429-430 

creating gcal resource files 
from, 558 
sorting, 492-493 
TIFF, converting to portable 
anymaps, 515-516 
time zone information, 
1197-1198 

timestamps (changing), 536 
transfer parameters, 153 
T rueVision T arga, convert¬ 
ing to portable pixmaps, 
515 

truncating, 879-880 
UNIX 

copying between systems, 
563-565 

copying to MS-DOS, 335 
restoring filenames 324- 
325 

U senix FaceSaver, convert¬ 
ing to portable graymaps, 
147 

user group, 1131 
UUCP transfer requests, 
processing, 1415-1417 
uuencode, format, 1200 
XFree86, 638-639, 
1201-1208 
Device actions 
1204-1206 


Filessection, 1201 
Keyboard section, 1202 
M onitor sections 
1203-1204 
Pointer section, 

1202-1203 
Screen sections 
1206-1208 

ServerFlagssection, 1201 
XIM , converting to portable 
pixmaps, 654 

YUV, converting to portable 
pixmaps, 730-731 
Z, recompressing to GZ, 
734-735 

Zeiss confocal, converting to 
portable anymaps, 732 
filesystem checks 

group identity (setting), 
843-844 

user identity (setting), 844 

filesystem description file, 
accessing, 935-936 
filesystems, 1125-1126 

buffers, flushing, 1401-1402 
building, 1325-1326 
checking, 1298-1300 
debugger, 1284-1285 
commands 1284-1285 
options 1284 

deleting names from, 1008 
device entries, maintaining, 
1320-1321 

dumping information, 1289 
ext, 1125 
ext2,1125 

hierarchy, description of, 
1236-1238 
H igh Sierra, 1125 
hpfs, 1125 
iso9660,1125 
MIN IX,1125 
consstency checker, 
1300-1301 
creating, 1326-1327 
mounting/dismounting, 
802-804,1328-1332 


msdos, 1125 
names, deleting, 882 
ncpfs, 1126 
nfs, 1125 

export list, 1123-1125 
proc, 1125 
quotas 

summarizing, 1376 
turning on/off, 

1372-1373 
repairing, 1298-1299 
Rock Ridge, 1125 
root, mounting, 849 
scanning, 1371-1372 
second extended 
checking, 1289-1291 
creating, 1324-1325 
lost+found directory, 1327 
tunable parameters 
(adjusting), 1412-1413 
setup, 849 
smb, 1126 
static information, 
1126-1127 

statistics, getting, 883-884, 
865-866 
sysv, 1125 
table of, 1427-1428 
type information, getting, 
871 

umsdos, 1125 
vfat, 1125 
xiafs, 1125 

filesystems command, 
1427-1428 
filters 

Laplacian relief, running on 
portable pixmaps, 413 
more, 327-328 
commands 328 
environment, 328 
options 327-328 
nonlinear (pnmnlfilt), 
390-391 
nroff output, 77 
reverse linefeeds, 76 
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find, 137-142 

actions, 140-142 
expressions, 138 
numeric arguments, 

138-140 
operators, 142 
options, 138 
findaffix, 274, 280 
bugs, 282 
files, 281 
seals) ispell 

finger daemons, configurable, 
1106-1109 

configuration file, 
1109-1115 
error messages, 1108 
features, 1107-1108 
SYSLOG messages, 1108 
finger information, changing, 
60 

finitef) function, 959 
first in - first out scheduling, 
833-834 

FITS files, converting to 
portable anymaps, 142-143 
fitstopnm, 142-143 
floating-point numbers 

absolute value, 919 
converting 

to fractional/integral 
components 927 
to strings 913-914, 
930-931 

extracting integral and 
fractional values, 984 
multiplying, by integral 
powers of 2, 961 

flock, 757 

floor() function, 923 
floppy disks 

devices, 1080-1083 

configuration, 1080-1082 
drivers, boot-time 
parameters, 1223-1224 
formatting, 1295-1296 
marking bad blocks, 316 
parameters, setting, 1391 
fmod() function, 923 



fmt, 143 

fnmatchf) function, 924 
fold, 143-144 
font files 

adding font-metric 
information, 2 
creating, 3 

font formats 

converting 

Bitmap Distribution to 
Portable Compiled, 47 
packed format to portable 
bitmaps 381 
PostScript PFB format to 
ASCII, 369 
groff_font, 1127-1129 
DESC file 1127-1128 
font servers (X) 

displaying information 
about, 145 

generating BD F fonts, 
146-147 

listing fonts, 145-146 

fonts 

files, 1128 

creating for groff, 513 
grops styles, 231-232 
man pages, 1247 
X 

displaying all characters 
in, 633-636 
Using, 670-671 
X font server, 641-643, 689 
configuration, 642 
naming, 643 

fopen function, 924-925 

errors, 925 

mode argument sequences, 
924-925 

return values, 925 

fork, 758 

form (ftp command), 149 
formatting 

dates, strftime() function, 
1032-1034 

documents, gtroff, 237-248 
equations, 202-206 
floppy disks, 1295-1296 


input, 1013-1015 

conversions 1014-1015 
flags 1014 
line lengths, 143 
man pages, 1246-1248 
fonts 1247 
macros 1248 
preamble, 1246-1247 
sections 1247-1248 
output, 992-996, 
1022-1023 

conversion specifiers 994 
examples 995 
flags 993-994 
technical papers 
groff_me macros 
1225-1227 
groff_mm macros 
1227-1234 
groff_ms macros 
1234-1236 

times, strftime() function, 
1032-1034 
troff tables, 236-237 

fpathconf() function, 
925-926 

fprintf function, 992-996 
fpurge function, 920-921 
fputc() function, 997-999 
fputs() function, 997-999 
fractal forgeries, 404-407 
fread function, 926-927 
free, 144 

free() function, 976 
freopen function, 924-925 
frexp() function, 927 
fscanf function, 1013-1015 
fsck, 1298-1300 
fsck.minix, 1300-1301 
fseek function, 927-928 
fsetpos function, 927-928 
fsinfo, 145 
fslsfonts, 145-146 
fstab, 1126-1127 
file format/options, 
1165-1167 
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fstat, 863-864 
fstatfs, 865-866 
fstobdf, 146-147 
fstopgm, 147 
fsync, 758-759 
ftell function, 927-928 
ftime function, 928-929 
ftok function, 929-930 
FTP (FileTransfer 
Protocol), D ARPA server, 
1301-1304 
ftp, 147-154 

aborting transfer, 152 
bugs, 154 

commands, 148-152 
I, 148 
$, 148 
?, 152 

account, 148 
appmd, 148 
ascii, 148 
bit, 148 
binary, 148 
bye, 148 
case, 148 
cd, 148 
cdup, 148 
chmod, 148 
close 148 
cr, 148 
debug, 149 
delete 148 
dir, 149 
disconnect, 149 
form, 149 
get, 149 
glob, 149 
hash, 149 
help, 149 
idle 149 
led, 149 
Is 149 
maedi, 149 
mde/ete 149 
mdir, 150 
mget, 150 
mkdir, 150 


mis 150 
mode, 150 
modtime, 150 
mput, 150 
newer, 150 
nlii, 150 
nmap, 150 
ntrans 150-151 
open, 151 
prompt, 151 
proxy ftp, 151 
put, 151 
pwd, 151 
quit, 151 
quote, 151 
reev, 151 
reget, 151 
remotehdp, 151 
remoteiatus 151 
rename, 151 
reset, 151 
reiart, 151 
rmdir, 152 
runique 152 
send, 152 
ssndport, 152 
site, 152 
sze, 152 
iatus 152 
iruct, 152 
yiem, 152 
trace, 152 
type, 152 
umask, 152 
user, 152 
verbose, 152 

environment variables, 154 
file naming conventions, 
153 

file transfer parameters, 153 
.netrefile, 153-154 
options, 147-148 
tenex, sendport, 152 

ftpd, 1301-1304 

bugs, 1303 

FTP requests supported, 
1302-1303 
options, 1302 


(truncate, 879-880 
ftw() function, 930 
full-duplex connections, 
shutting down, 855 
function bindings, displaying, 
35 

functions 

calling at termination, 
897-898, 988 

headers, displaying, 455-456 
library, undocumented, 

1060 

portable pixmap programs, 
973-974 
color names 974 
memory management, 973 
reading files 974 
writing files 974 
fuser, 154-155 
fwrite function, 926-927 

G 

g++, 155-160,174-201 

bugs, 160 
copying, 160, 201 
filename suffixes, 174-175 
files, 159-160, 200 
options, 155-159,175-178 
assembler, 181 
codegeneration, 198-199 
debugging, 186-187 
directory, 182-183 
language, 178-180 
linker, 181-182 
machinedependent, 
191-198 

optimization, 188-190 
preprocessor, 180-181 
target, 190-191 
warning, 183-186 
pragmas, 159, 200 
g3topbm, 160-161 
games, 1210 
gawk, 161-173 
actions, 165-166 
arithmetic functions, 
168-169 
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bugs, 172 

reporting, 172-173 
control statements, 167 
environment variables, 172 
fields, 163 
functions, 170 
GNU extensions, 171 
historical awk features 
supported, 172 
I/O statements, 167 
operators, 166-167 
options, 161-162 
patterns, 165-166 
POSIX compatibility, 171 
printf statement, 167-168 
program execution, 162-163 
regular expressions, 166 
special filenames, 168 
sprintff) function, 167-168 
string constants, 169-170 
string functions, 169 
time functions, 169 
variables, 163-165 
arrays, 164 
built-in, 163-164 
typing and converson, 
164-165 

version information, 172 
gcal, 173-174 

running one day ahead, 506 
resource files, creating from 
text files, 558 
gcc, 174-201 

assembling output, 8-9 
bugs, 201 
copying, 201 

filename suffixes, 174-175 
files, 200 
options, 175-178 
asembler, 181 
codegeneration, 198-199 
debugging, 186-187 
directory, 182-183 
language, 178-180 
linker, 181-182 
machine-dependent, 
191-198 


optimization, 188-190 
preprocessor, 180-181 
target, 190-191 
warning, 183-186 
pragmas, 200 

gcvt() function, 930-931 
GEM IMG files, converting to 
portable bitmaps, 201 
gemtopbm, 201 
GenerateM essagelD routine, 

964 

geqn, 202-206 

automatic spacing, 203 
bugs, 206 

customization, 204-205 
equation components, 
202-203 
files, 206 
fonts, 206 
macros, 206 

new primitives, 203-204 
options, 202 

get (ftp command), 149 
get current_dir_name() 
function, 931 
get empty filp, 1428 
get kernelsyms, 800-802 
getc() function, 945 
getchar() function, 945 
GetConfigValue routine, 965 
getcwd() function, 931 
getdents, 759 
getdirentries function, 

931-932 

getdomainname, 760 
getdtablesize, 760-761 
getegid, 761 
getenv() function, 932 
geteuid, 773 

GetFileConfigValue routine, 

965 

GetFQD N routine, 965 
getgid, 761 

getgrent() function, 932-933 
getgrgid() function, 933-934 
getgrnam() function, 933-934 
getgroups, 761-762 


gethostid, 762-763 
gethostname, 763 
getitimer, 763-764 
getlist, 206-207 
getlogin() function, 934-935 
getmntent() function, 

935- 936 

GetM oderatorAddress 
routine, 965 

getnetbyaddr subroutine, 

936- 937 

getnetbyname subroutine, 
936-937 

getnetent subroutine, 936-937 

getopt, 207-208 

getopt() function, 937-940 

environment variables, 939 
getopt_long() example, 
939-940 

return value, 939 

getopt long() function, 
938-940 

getopt long only() function, 
938 " 

getopts (shell command), 38 
getpagesize, 765 
getpass function, 940-941 
getpeername, 765 
getpgid, 845-846 
getpgrp, 845-846 
getpid, 766 
getppid, 766 
getpriority, 766-767 
getprotobyname() function, 
941-942 

getprotobynumber() 
function, 941-942 
getprotoent() function, 
941-942 

getpw() function, 942-943 
getpwent() function, 943 
getpwnam() function, 944 
getpwuid() function, 944 
GetResourceU sage routine, 
965 

getrlimit, 767-768 
getrusage, 767-768 
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gets() function, 945 
getservbyname() function, 
946 

getservbyport() function, 946 
getservent() function, 946 
getsid, 768 
getsockname, 769 
getsockopt, 769-772 
bugs, 772 
errors, 771 

options recognized, 770-771 
SO_BROAD CAST, 771 
SO_D EBUG, 770 
SO_DONTROUTE, 770 
SO_ERROR, 771 
SO_KEEPALIVE, 770 
SO_LINGER, 770 
SO_RCVBUF, 771 
SO_RCVLOWAT, 771 
SO_RCVTIM EO, 771 
SO_REUSEADDR, 770 
SO_SN D BU F, 771 
SO_SNDLOWAT, 771 
SO_SNDTIM EO, 771 
SO TYPE, 771 
return value, 771 
GetTimelnfo routine, 965 
gettimeofday, 772-773 
getuid, 773 

getusershell() function, 
946-947 

getutent() function, 947 
getutid() function, 947 
getutline() function, 948 
getw function, 948 
getwd() function, 931 
GIF files, converting to 
portable anymaps, 208-209 
giftopnm, 208-209 
giles, gpic, 215 
gindxbib, 209-210 
glob (ftp command), 149 
glob() function, 949-950 
glob_dot_filenames variable 
(bash), 17 

globfree() function, 949-950 


glookbib, 210 
gmtime, 984-986 
gmtime() function, 909-910 
gnroff, 210-211 
GNU linker, 287-291 
copying, 291 
environment, 291 
options, 288-291 
GNU ar, see ar 
GNU as, see as 
GNU Bourne-again shell,see 
bash 

Gould scanner files, convert¬ 
ing to portable pixmaps, 211 
gouldtoppm, 211 
gpic, 211-215 

bugs, 215 

commands, 212-213 
expressions, 213-214 
file, 215 
mode, 212 
options, 211-212 
versus pic, 212-215 
gprof, 216-217 

graph profile data, displaying, 
216-217 

graphics (ASC11), converting 
to portable graymap, 10 
graphs 

system load average, 533 
topological sorts, 542 

grayscale ramps, generating, 
374-375 

greater than signs (>), 
redirection operator, 21 
grefer, 217-224 

bibliographic databases, 219 
bugs, 224 
citations, 219-220 
commands, 220-222 
files, 224 

label expressions, 223-224 
macro interface, 224 
options, 218-219 


grep, 224-226 

bugs, 226 
diagnostics, 226 
options, 224-225 
regular expressions, 225-226 

grodvi, 227-228 
groff, 228-230 

availability, 230 
bugs, 230 

creating font files for, 513 
environment, 229 
files, 229 

guessing options, 230 
interpreting .so requests, 

236 

options, 229 

output, converting to T eX 
dvi format, 227-228 
PostScript driver, 230-235 
preprocessing references, 
217-224 

typewriter device driver, 235 

groff font format, 1127-1129 

D ESC file, 1127-1128 

groffme, 1225-1227 
groffmm, 1227-1234 

extensions, 1227-1229 
number variables, 
1233-1234 
strings, 1233 
variables, 1229-1230 
groff ms, 1234-1236 
groff out, 1129-1131 
grog, 230 
grops, 230-235 
files, 234 

font styles, 231-232 
options, 231 
X commands, 232-233 

grotty, 235-236 
group, 1131 

Group 3 fax files, converting 
to portable bitmaps, 

160-161 

group access lists 

getting/setting, 761-762 
initializing, 955 
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group file entries, getting, 
921-922, 932-934 
group identity, setting, 845 
group IDs 

getting/setting, 761, 

845- 846 

real and effective, setting, 

846- 847 

group ownership (files), 
changing, 61 
groups 

adding to system, 

1258-1259 
logging into, 336-337 
process, sending signals to, 
960 

grow_ files, 1428-1429 
grttoppm, 436-437 
gsoelim, 236 
gtbl, 236-237 
gtroff, 237-248 
environment, 248 
escape sequences, 239-240 
files, 248 

fractional point sizes, 238- 
239 

incompatibilities, 247-248 
long names, 238 
numeric expressions, 239 
options, 238 
requests, 241-244 
extended, 244 
number registers 245-246 
warnings, 246-247 
gunzip, 248-249 
see a/so gzip 
gzexe, 252-253 
gzip, 248-252 
bugs, 252 

diagnostics, 251-252 
environment, 251 
options, 249-250 

gzip files, forcing .gz exten¬ 
sion, 732-733 



H 


handling signals, 857-858 
hard disks 

boot-time parameters, 
1220-1221 
devices, 1083 

partition tables, manipulat¬ 
ing, 1296-1297 

hard drives, partitioning, 
1265-1269 

hard-reset() action (xterm), 
715 

hardware, video (identifying), 
501-503 
hash 

ftp command, 149 
shell command, 38 

hash tables 

creating, 951 
freeing memory, 951 
searching, 951 

hasmntopt() function, 
935-936 

hcreate() function, 951-952 
hd, 1083 

hdestroy() function, 951 
head, 253-254 
HeaderC lean From routine, 
964 

HeaderFind routine, 964 
headers function, displaying, 
455-456 
help 

ftp command, 149 
shell command, 38 
xauth command, 591 

here-documents, 22-23 
hexdump, 254-256 
hier, 1236-1238 

directories, 1236-1238 
/, 1236 
/bin, 1236 
/boot, 1236 
/da/, 1236 
/dos 1236 
/etc, 1236 


/Ac/ s/cd, 1236 
/etc/XU, 1236 
/home, 1236 
/lib, 1236 
/mnt, 1236 
/proc, 1236 
/sbin, 1237 
/tmp, 1237 
/US', 1237 
/US-/X11R6,1237 
/usr/XHR 6/bin, 1237 
/us r /XHR6/lib, 1237 
/us r /XHR6/lib/Xll, 1237 
/usrX 11R 6/includdX 11, 
1237 

hierarchies 

directory (creating), 323 
filesystem, description of, 
1236-1238 

H igh Sierra filesystem, 1125 
HIPS files, converting to 
portable graymaps, 256 
hipstopgm, 256 
histchars variable (bash), 

17-18 

HISTCMD variable (bash), 

16 

HISTFILE variable (bash), 17 
HISTFILESIZE variable 
(bash), 17 
histograms 

drawing for PGM or PPM 
files, 388 

portable pixmaps, printing, 
408 

history, 1131-1132 

control variable (bash), 17 
cvs command, 99 
shell command, 39 

history expansion (bash), 
33-34 

event designators, 33 
modifiers, 34 
word designators, 33 

history lists (bash), 32-33 

displaying, 39 

HISTSIZE variable (bash), 17 
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HOME variable (bash), 16 
/home directory, 1236 
horizontal-scroll-mode 
variable (readline), 28 
host, 257-258 
bugs, 258 
customizing, 258 
options, 257-258 
host byte order, converting 
between network byte order, 
901-902 

host ID s, printing, 258-259 
hostid, 258-259 
hostname, 259-260, 
1238-1239 

hostnamecompletionfile 
variable (bash), 18 
hostnames 

displaying, 259-260 
looking up, 257-258 
resolving, 1238-1239 

hosts 

identifiers, getting/setting, 
762-763 

names, getting/setting, 763 
sending messages to users 
on, 473 

hostsmntp, 1132-1133 
hosts.nntp.nolimit, 

1132-1133 

hosts_ access, 1133-1136 

access control files, 1133 
access control rules, 1133 
bugs, 1136 
diagnostics, 1136 
files, 1136 
operators, 1134 
patterns, 1133-1134 
remote username lookup, 
1134-1135 

shell commands, 1134 
wildcards, 1134 

hosts access!) function, 
950-951 

hosts_ctl() function, 950-951 
hosts_ options, 1137-1139 

diagnostics, 1139 
options, 1137 


HOSTTYPE variable (bash), 
16 

HP PaintJet files, converting 
to portable pixmaps, 381 
hpcdtoppm, 260-261 
hpfs filesystem, 1125 
hsearch() function, 951-952 
htonl() function, 901-902 
htons() function, 901-902 
httpd, 261 

hyperbolic cosines, 908 
hyphens (-), bash special 
parameters, 15 
hypot() function, 953 


I/O 

awk statement, 167 
port permissions, setting, 
788 

ports, functions, 816 
privilege level, changing, 
788-789 

standard I/O library, 
1025-1027 

ICC cancel routine, 956 
ICC close routine, 956 
ICC command routine, 956 
1C Copen routine, 956 
ICC pause routine, 956 
ICC reserve routine, 956 
ICCsettimeout routine, 956 
icombine, 274, 281 
files, 281 
seea/so ispell 
icontopbm, 262 
ident, 262-263 
idlet 774 
errors, 774 
ftp command, 149 
return value, 774 
ID s(group), searching for 
matches, 1429 

$if parser directive (readline), 
28-29 

ifconfig, 1304-1305 


IFS variable (bash), 16 
ignore() action (xterm), 713 
IGNOREEOF variable (bash), 
17 

ijoin, 274, 281 

files, 281 
seea/so ispell 

ILBM files, converting to 
portable pixmaps, 263-264 
ilbmtoppm, 263-264 
image files, converting to 
portable anymap, 4 
image parameter, values, 1374 
imake, 264-267 

environment variables, 267 
files, 266 
input, 266 
options, 265 
X Window System, 266 
Imakefiles, creating Makefiles 
from, 672 

Img-whatnot file, converting 
to portable pixmaps, 267 
imgtoppm, 267 
import (cvs command), 100 
ingroupp, 1429 
inb, 816 
inb p, 816 

inbound zone transfers, 
1333-1334 

index!) function, 953 
indexes, archives (generating 
for), 437-438 
inet addr() function, 954 
inet_aton() function, 954 
inet_lnaof() function, 954 
inet makeaddr!) function, 
954 

inet_netof() function, 954 
inet_ network!) function, 954 
inet ntoa() function, 954 
inetd, 1305-1307 
inews, 267-269 
infinite results 

returning valuefor, 954-955 
testing for, 959 
infnan() function, 954-955 





info, 269-270 

commands, 269-270 
environment, 270 
options, 269 

info command (xauth), 591 
init, 1307-1309 
diagnostics, 1309 
files, 1308 
run levels, 1308 
init_ module, 800-802 
init_ timer, 1424 
initgroupsf) function, 955 
initializing 

terminals, 539-542 
X sessions, 496-497 
initstate() function, 
1001-1002 
inittab, 1139-1141 
inittab file, 1398 
ini, 816 
inlp, 816 

inn.conf, 1141-1142 
innconfval, 270-271 
innd, 1309-1312 

control messages, 1310 
header modifications, 1311 
logging, 1311-1312 
protocol differences, 
1310-1311 

inndcomm routines, 956 
inndstart, 1309-1312 
INNVersion routine, 966 
innwatch.ctl, 1142-1144 
innxmit, 1312-1313 
input 

formatting, 1013-1015 
conversion s 1014-1015 
flags 1014 
reading, 27-32 

controlling key bindings 
27 

denoting keystrokes 21 
macro definitions 28 
readline commands 
29-32 

redirecting, 22 
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input lines, wrapping, 143- 
144 

input, see el vis 

INPUTRC variable (bash), 17 
insb, 816 

insert() action (xterm), 713 
insert-eight-bit() action 
(xterm), 713 
insert-selection!) action 
(xterm), 713 
insert-seven-bit() action 
(xterm), 713 
insertfilefree, 1429 
insl, 816 

insmod, 271-272 
insque() function, 957 
install, 272-273 
installing 

loadable modules, 271-272 
rstartd, 469 
spottopgm, 495 
sysklogd, 1403 

in stall it, 273-274 
insw, 816 
integers 

absolute values, 892-893 
converting, between host 
and network byte order, 
901-902 
dividing, 911 

floating-point remainders 
913, 923 

returning quotient and 
remainder, 961 
long, labs, 960-961 
rounding, 904 
downward, 923 
to, 1011-1012 
interactive shells, 45 
interfaces 

name daemon control, 
1338-1339 
network 

attaching to serial line 
1399 

configuring, 1304-1305 


serial mouse, 1092-1094 
M icrosoft protocol, 1093 
M M protocol, 1094 
M ous£ystems protocol, 
1093 

Sun protocol, 1093 

interned atoms, listing, 
668-669 
Internet 

addresses, manipulating, 
953-954 

extended I nternet services 
daemon, 655-664 
inetd superserver, 
1305-1307 

services, listing, 1184-1186 

I nterN etN ews 

buffered file-writing, 1264- 
1265 

configuration data, 
1141-1142 
daemon, 1309-1312 
control messages 1310 
controlling, 1276-1279 
file-writing, 1297-1298 
I nterN etN ews library 
dientlib, 904-905 
INND communication 
routines, 956 
libinn routines, 962-966 
CAdose, 964 
CAIistopen, 964 
CAopen, 964 
Cl09eOnExec, 965 
DD check, 965 
DDend, 965 
DD start, 965 
GetConfigValue, 965 
GetFileConfigValue, 965 
GetFQDN, 965 
GetM oderatorAddress, 
965 

GetResourceU sage 965 
GetTimelnfo, 965 
H eaderFind, 964 
INNVersion, 966 
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LockFile, 965 
NNTPcheckartide 965 
NNTPconnect, 965 
N NT P local open, 965 
NNTPremoteopen, 965 
NNTPxndarticle, 966 
NNTPsndpamord, 966 
Radix32, 966 
ReadlnDescriptor, 966 
ReadlnFile, 966 
SetN onBlocking, 965 
Quick I/O, 998 
interrupt key sequence, 
routing, 1425 
interval timers 

getting/setting value, 
763-764 

IT IM ER_PROF, 764 
IT IM ER_REAL, 764 
IT IM ER_VIRTUAL, 764 
value definitions, 764 

inverse hyperbolic cosines, 
893-894 

inverse hyperbolic sines, 895 
inverse hyperbolic tangents, 
897 

inverted indexes, biblio¬ 
graphic databases, 209-210 
invocation, bash, 45-46 
inw, 816 
inw p, 816 
ioctf, 774-788 

arguments, 787-788 
calls 

consoles 1074-1080 
fd device support, 1082 
list of, 715-186 
Ip, 1090-1091 
sd, 1095-1096 
st, 1097-1100 
duplicates, 788 
errors, 774 
return value, 774 
ioperm, 788 
iopl, 788-789 
errors, 789 
return value, 789 


IP 

dialup connections, handler, 
1285-1288 

routing table (manipulat¬ 
ing), 1379-1380 
ipc, 789,1144-1146 

message queues, 1145 
resource access permissions, 
1144-1145 

semaphore sets, 1145-1146 
shared memory segments, 
1146 

ipc facilities 

getting information on, 

1314 

removing, 1313-1314 

IPC system calls, 789 
ipcrm, 1313-1314 
ipcrs, 1314 

isalnum() function, 958 
isalpha() function, 958 
isascii() function, 958 
isatty function, 958-959 
isblank() function, 958 
iscntrl() function, 958 
isdigit() function, 958 
isgraph() function, 958 
isinf() function, 959 
islower() function, 958 
isnan() function, 959 
ISO character sets 
2022,1066 
4873,1066 
8859,1064-1065 
8859-1,1239-1242 
alphabets 1240 
characters 1240-1242 
iso9660 filesystem, 1125 
ispell, 274-279,1084-1090 
affix file, 1084-1085 
alternate string characters, 
1087 
bugs, 282 

capitalization rules, 279 
character-set section, 1086 
commands, 274-275 
flags, 1088 


headers, 1085 
options, 275-279 
options statements, 
1085-1086 

prefix/suffix tables, 1088 
root words 
case, 1084 
extending, 1085 
modifying, 1088-1089 
isprint() function, 958 
ispunct() function, 958 
isspace() function, 958 
issue, 1146-1147 
isupper() function, 958 
isxdigit() function, 958 
ITIM ERPROF interval 
timer, 764 

ITIM ERREAL interval 
timer, 764 

ITIM ERVIRTUAL interval 
timer, 764 

J 

j0() function, 959 
jl() function, 959 
jn() function, 959 
job control, 24-25 
jobs, displaying, 39 
jobs (shell command), 39 
join, 282-283 
jrand48() functions, 912 

K 

kbdrate, 1314-1315 
Kerberos authentication, 461 
kernel 

boot-time parameters, 
1216-1224 

Adaptec configurations 
1219-1220 

argument list, 1216-1217 
B usL ogic configuration, 
1220 

busmous drivers 1224 
cards not accepting, 1220 
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CD-ROMs 1222-1223 
debug argument, 1217 
Ethernet da/ices, 1223 
floppy did< drivers 
1223-1224 

future domain configura¬ 
tion, 1220 

harddisks 1220-1221 
mem= argument, 1218 
no-hit argument, 1217 
no387 argument, 1217 
Pro A udio configuration, 
1220 

ramdisk= argument, 1218 
reboot=warm argument, 
1218 

reserve^ argument, 

1217- 1218 

ro argument, 1217 
root= argument, 1217 
rw argument, 1217 
SCSI da/ice arguments, 

1218- 1219 

SCSI tape configuration, 
1219 

Seagate ST-Ox 
configuration, 1220 
sound drivers 1224 
TrantorT128 
configuration, 1220 
exported symbols, display¬ 
ing, 284-285 
log buffer, 873 
message ring buffer, reading/ 
clearing, 872-874 
modules, loading at boot 
time, 1152 

name, getting, 880-881 
ring buffer, controlling, 
1288-1289 

kernel clock, adjusting, 
742-743 

kernel log daemon, 

1315-1317 
kernel logging, 1402 
kernelmktime, 1430 
key bindings, displaying, 35 



key combinations, 
Ctrl+Alt+Del (setting 
function), 1279 
key sequences (interrupt), 
routing, 1425 
keyboard repeat rate, 
resetting, 1314-1315 
keymap variable (readline), 28 
keymap() action (xterm), 713 
keymaps(X), modifying, 
672-676 

keywords, RCS, identifying in 
files, 262-263 
kill, 283-284, 790 

bugs, 790 
errors, 790 
options, 283 
return value, 790 
shell command, 39 
killall, 284 

killing client connections (X 
servers), 666-667 
killpg, 790-791, 960 
klogd, 1315-1317 

files, 1317 
options, 1315 

signal handling, 1316-1317 

kmem, 1091-1092 
KOI8-R character set, 1065 
ksyms, 284-285 

L 


labs() function, 960-961 
Laplacian relief filters, 
running on portable 
pixmaps, 413 
last, 285-286 

Latin-1 character set, 1064 
Latin-2 character set, 1064 
Latin-3 character set, 1064 
Latin-4 character set, 1064 
Latin-5 character set, 1065 
Latin-6 character set, 1065 
Ibxproxy, 286-287 

network connections, 286 
options, 286 


led (ftp command), 149 
lcong48() functions; 912 
Id, 287-291 

copying, 291 
environment, 291 
options, 288-291 

ldexp() function, 961 
ldiv() function, 961 
less than signs (<), redirection 
operator, 21 
let (shell command), 39 
letters, converting 

to lowercase, 1055-1056 
to uppercase, 1055-1056 
lfind() function, 975-976 
lgamma() function, 962 
/lib directory, 1236 
libinn routines, 962-966 
CAdose, 964 
CAIistopen, 964 
CAopen, 964 
CloseOnExec, 965 
DD check, 965 
DDend, 965 
DD start, 965 
G etConfigValue, 965 
G etFileC onfigValue, 965 
GetFQ D N , 965 
GetM oderatorAddress, 965 
GetResourceUsage, 965 
GetTimelnfo, 965 
H eaderFind, 964 
IN N Version, 966 
LockFile, 965 
N NTPcheckartide, 965 
N NTPconnect, 965 
N NTPIocalopen, 965 
N NTPremoteopen, 965 
N NTPsendarticle, 966 
N N T P send password, 966 
Radix32, 966 
R ead I n D escri ptor, 966 
ReadlnFile, 966 
SetN onBlocking, 965 
libpbm routines, 966-969 
constants, 968 
endian i/o, 967 
errors, 967 
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file management, 967 
initialization, 968 
keyword matching, 967 
memory management, 968 
messages, 967 
reading files, 968 
types, 968 

writing files, 968-969 
libpgm routines, 969-970 

constants, 969 
initialization, 969 
memory management, 969 
reading files, 970 
types, 969 
writing files, 970 
libpnm routines, 970-972 
constants, 970 
format promotion, 972 
initialization, 971 
memory management, 971 
reading files, 971 
types, 970 

writing files, 971-972 
XEL manipulation, 972 
XEL manipulations, 971 
libppm, 973-974 
color names, 974 
memory management, 973 
reading files, 974 
writing files, 974 
libraries 

shared, selecting, 883 
standard I/O, 1025-1027 

library functions, undocu¬ 
mented, 1060 
LILO, 1216 

configuration file, 

1147-1151 

global options 1148-1149 
kernel options 1150-1151 
per-imagesection, 
1149-1150 

line buffered streams, 1016 
line printer 

control program, 1317-1318 
da/ices, 1090-1091 
ioctlf) calls 1090-1091 
spooler daemon, 1318-1320 


linear searches, arrays, 
975-976 

LINENO variable (bash), 15 
link, 791-792 
linkers, Id (GNU linker), 
287-291 

copying, 291 
environment, 291 
options, 288-291 

linking files, 293-294, 791- 
792 

Lisp M achine bitmap files, 
converting to portable 
graymaps, 292 
lispmtopgm, 292 
list 

bash command, 13 
xauth command, 591 

listen, 792-793 
lists 

bash, 12-13 
columnating, 78 
variable argument (declar¬ 
ing), 1023-1024 

Ikbib, 292-293 
llseek, 793 
In, 293-294 
Indir, 294 
loadable modules 
installing, 271-272 
support, 800-802 
unloading, 462-463 
viewing, 305 
loadlin program, 1216 
local (shell command), 39 
local descriptor table, reading/ 
writing, 800 

local variables, creating, 39 
locale, 1243-1244 
setting, 1018-1019 
localeconv, 974-975 
localtime, 909-910,984-986 
locate, 295 

lock files, creating for shell 
scripts, 487 
LockFile routine, 965 


locking memory 
mlock, 796-797 
mlockall, 797-798 

locks (advisory), applying/ 
removing open files, 757 
log (cvs command), 100 
log() function, 918 
Iogl0() function, 918 
loglp() function, 918 
logarithms, 918 
1 plus argument, 918 
base-10, 918 
logger, 295-296 
logging 

innd, 1311-1312 
kernel, 1402 
system, 1402-1404 
configuration file 
1402-1403 
FIFOs 1403 
mesages 1404-1405 
remote, 1403 
U senet, log file 
maintenance, 1346-1347 
login, 296-297 
login shells, 45 
changing, 63 
exiting, 39 
logins 

changing groups, 336-337 
displaying last, 285-286 
login command, 296-297 
login record files, 

1198-1200 
preventing, 1168 
remote, 460-461 

K erberos au then ti cation, 
461 

root, tty lines (listing), 1184 
shells, pathnames, 1186 

logout (shell command), 39 
logs 

system 

making entries, 295-296 
sending mesages to, 
1045-1046 
xinetd, 661-663 





long integers, absolute values, 
960-961 

longjmp() function, 975 
look, 297-298 
loops 

exiting, 35 
resuming, 36 

lowercase, converting letters 
to, 1055-1056 
Ip, 1090-1091 

Ip devices, setting parameters, 
1413-1414 

l pc, 1317-1318 

commands, 1317-1318 
diagnostics, 1318 

l pd, 1318-1320 

key characters, 1319 
options, 1319 

l pq, 298-299 
bugs, 299 
diagnostics, 299 
environment, 299 
options, 298-299 

l pr, 299-301 
bugs, 301 
diagnostics, 301 
environment, 300 
options, 299-300 

Iprm, 301-302 
bugs, 302 
diagnostics, 302 
environment, 302 
options, 301 
Iptest, 302 

Irand48() functions, 912 

Is, 303-304 

Is (ftp command), 149 

Isattr, 304-305 

lsearch() function, 975-976 

I seek, 793-794 

Ismod, 305 

Istat, 863-864 

lynx, 306-309 

commands, 308-309 
options, 306-308 
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macdef (ftp command), 149 
Macintosh PICT files, 
converting to portable 
pixmaps, 379-380 
M acPaint files, converting to 
portable bitmaps, 309-310 
macptopbm, 309-310 
magic cookies, generating, 

317 

mail addressing, 1244-1246 

abbreviations, 1245 
case sensitivity, 1245 
compatibility, 1245 
postmasters, 1246 
routing, 1245 
mail, see e-mail 
MAIL variable (bash), 16 
MAIL WARNING variable 
(bash), 16 

mailaddr, 1244-1246 

abbreviations, 1245 
bugs, 1246 
case sensitivity, 1245 
compatibility, 1245 
postmasters, 1246 
routing, 1245 

MAILCHECK variable (bash), 
16 

MAILER environment 
variable, 529 

MAILPATH variable (bash), 
16 

make, 310-312 

imake preprocessor, 264-267 
options, 311 

makeactive, 1342-1344 
makedepend, 312-314 

algorithm, 313 
bugs, 314 
options, 312-313 

MAKEDEV, 1320-1324 

files, 1321 
options, 1321-1324 

MAKEDEV.cfg, 1151 


makefiles 

creating dependencies in, 
312-314 

creating from I makefiles, 
672 

makehistory, 1342-1344 
makestrs, 314-315 

bugs, 315 
directives, 315 
options, 314 
syntax, 314-315 

malloc() function, 976 
man, 1246-1248 
man pages, formatting, 
1246-1248 

fonts, 1247 
macros, 1248 
preamble, 1246-1247 
sections, 1247-1248 

mapping files to memory, 
799-800 

mark-modified-lines variable 
(readline), 28 

mask bitmaps, creating from 
regular, 353-354 
masks, file-creation, 880 

setting, 45 

mattrib, 315-316, 330 
mbadblocks, 316, 330 
mblen, 977 
mbstowcs() function, 

977- 978 

mbtowc() function, 978 
mcd, 316-317, 330 
mcookie, 317 
mcopy, 317-318, 330 
M D 5 message digests, 
generating/checking, 318 
md5sum, 318 
mdel, 318-319, 330 
mdelete (ftp command), 149 
mdeltree, 319 
mdir, 150, 319, 330 
mem, 1091-1092 
memccpy() function, 901, 

978- 979 

memchr() function, 901, 979 
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memcmp() function, 901, 

979- 980 

memcpy() function, 901, 980 
memfrob() function, 901, 

980- 981 

memmem() function, 901, 
981 

memmove() function, 901, 
981 

memory 

access, controlling, 804-805 
allocating, 894, 976 
displaying amount, 144 
freeing, 976 
kernel, 1091-1092 
locking 

mlock, 796-797 
mlockall, 797-798 
mapping/unmapping files 
to, 799-800 
reallocating, 976 
scanning for characters, 979 
shared 

allocating, 851-853 
controlling, 849-851 
operations 853-854 
system, 1091-1092 
unlocking 

munlock, 811-812 
munlockall, 812-813 
virtual 

remapping addresses 
805-806 

reports, 1417-1418 
virtual console, 1101-1102 
memory areas 

comparing, 979-980 
copying, 978-981 
encrypting, 980-981 
filling with constant bytes, 
982 

locating substrings in, 981 

memset() function, 901, 982 
merge, 320 

merge command (xauth), 591 
merging files, three-way, 320 
mesg, 321 


message catalogs 

getting messages from, 
902-903 

opening/closing, 903-904 

message queue identifier, 
retrieving, 807-808 
messages 

control, 1310 

control operations, 806-807 
displaying, 321 
log (RCS files), printing, 
458-460 

message of the day file, 1152 
receiving, from sockets, 
826-828 

sending/receiving, 808-811 
sending 

from sockets 842-843 
to system logger, 
1045-1046 
to users, 473, 516-577 
signal, printing, 996 
system console, monitoring 
with X, 597-598 
system error, printing, 
990-991 

systems, logging, 1404-1405 
U senet control, handling, 
1115-1116 

writing to users, 574,1383 

meta characters (bash), 12 
meta-flag variable (readline), 
28 

mformat, 321-322, 330 
bugs, 322 
options, 321-322 
mget (ftp command), 150 
MGR bitmaps, converting to 
portable bitmaps, 322-323 
mgrtopbm, 322-323 
MINIX filesystems, 1125 
consistency checker, 
1300-1301 
creating, 1326-1327 
mkdir, 150, 323, 794-795 
bugs, 795 
errors, 795 


options, 323 
return value, 795 

mkdirhier, 323 
mke2fs, 1324-1325 
mkfifo, 323-324, 982-983 
errors, 982-983 
options, 324 
mkfs, 1325-1327 
mklost+found, 1327 
mkmanifest, 324-325 
mknod, 325, 795-796 
bugs, 796 
errors, 796 
options, 325 
return value, 796 
mkstemp() function, 983 
mkswap, 1327-1328 
mktemp() function, 983-984 
mktime, 910,984-986 
mlabel, 325-326, 330 
mlock, 796-797 
mlockall, 797-798 
mis (ftp command), 150 
mmap, 799-800 
mmd, 326, 330 
mmount, 326-327, 330 
mmove, 327, 330 
/ mnt directory, 1236 
mode (ftp command), 150 
mode command (telnet), 508 
mode parameter, values, 1374 
modems, conversational 
exchanges, 1269-1273 
abort strings, 1270-1271 
chat script, 1270 
escape sequences, 

1271-1272 
report strings, 1271 
termination codes, 1272 
time-out value, 1271 
moderators, 1151-1152 
modf() function, 984 
modify Idt, 800 
modprobe, 109-112 
configuration, 110-111 
files, 111 
strategy, 111 
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modtime (ftp command), 150 
modules 

kernel, loading at boot time, 
1152 
loadable 

support, 800-802 
unloading, 462-463 
viewing, 305 

more, 327-328 
motd, 1152 

mount, 802-804,1328-1332 

bugs, 1332 
errors, 803 
files, 1332 
options, 1329-1331 
return value, 803 
mountd, 1332-1333 
mounting M S-D OS disks, 
326-327 

mouse, 1092-1094 

M icrosoft protocol, 1093 
M M protocol, 1094 
M ouseSystems protocol, 
1093 

Sun protocol, 1093 

mprotect, 804-805 
mput (ftp command), 150 
mrand48() functions, 912 
mrd, 329-330 
mread, 329 
mremap, 805-806 
mren, 329-330 
MS-DOS 
directories 

changing, 316-317 
displaying, 319 
trees, deleting, 319 
disks, mounting, 326-327 
files 

changing attribute flags 
315-316 

copying to/from UNIX, 
317-318, 329 
deleting, 318-319 
displaying contents 
333-334 

manipulating (mtools I, 
330-333 


moving, 327 
renaming, 329-330 
filesystems, adding to disks, 
321-322 

floppies, marking bad 
blocks, 316 
subdirectories 
creating, 326 
moving, 327 
removing, 329 
renaming, 329-330 
volume labels, creating, 
325-326 

msdos filesystem, 1125 
msgctl, 806-807 
msgget, 807-808 
msgop, 808-811 
msync, 811 
mtest, 330 

mtools, 330-333,1152-1158 

bugs, 333 

case sensitivity of V FAT, 
332 

character translation tables, 
1155-1157 

configuration files, testing, 
330 

default values, 1153 
drive geometry 
configuration, 1154-1155 
exit codes, 333 
general purpose drive 
variables, 1153-1154 
global variables, 1153 
long filenames, 331 
mattrib, 330 
mbadblocks, 330 
mcd, 330 
mcopy, 330 
mdel, 330 
mdir, 330 
mformat, 330 
mlabel, 330 
mmd, 330 
mmount, 330 
mmove, 330 
mrd, 330 


mren, 330 
mtest, 330 
mtype, 330 

multiple descriptions, 1155 
name clashes, 332 
open flags, 1155 
parsing order of files, 
1157-1158 

per-drive flags/variables, 
1153 

working directory, 331 
Xdf disks, 332 

M TV ray tracers, converting 
output to portable pixmaps, 
333 

mtvtoppm, 333 
mtype, 330,333-334 
multilanguage support 
(description), 1243-1244 
multibyte characters, 
converting to wide 
characters, 978 
multibyte strings, converting 
to wide character, 977-978 
multiple buffers, reading/ 
writing data, 1003-1004 
multiuser chat program, 
727-730 

Boolean options, 729 
daemons, 727 
escape menu, 728 
readdressing, 729 
runtime options, 728-729 
startup file, 729 
username field, 727 
Xll interface, 730 
munchlist, 274, 279 
bugs, 282 
files, 281 
options, 279-280 
seea/so ispell 
munlock, 811-812 
munlockall, 812-813 
munmap, 799-800 
mv, 334-335 
mwrite, 335 
mysnc, 811 
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named, 1334-1338 

boot file, 1334-1336 
files, 1337 
master file, 1336 
options, 1334 
signals, 1337 
SO A record, 1336-1337 
named pipes, see FIFOs 
named-xfer, 1333-1334 
named.reload, 1338 
named.restart, 1338 
namei, 335-336 
options, 336 
output, 335 
names 
bash, 12 

peer, getting, 765 
socket, getting, 769 
nameserver (Internet 
domains), 1334-1338 

boot file, 1334-1336 
control interface, 1338-1339 
master file, 1336 
querying, 1350-1353 
signals, 1337 
SO A record, 1336-1337 
stopping/restarting, 1338 
synchronizing database, 

1338 

naming 

font servers, 643 
temporary files, 1049,1054 
xhost, 644 

NaN (not-a-number) results 
returning value for, 954-955 
testing for, 959 

nanosleep, 813-814 
ncpfs filesystem, 1126 
ndc, 1338-1339 
Netnews reader, see tin 
.netrc file, 153-154 
netstat, 1339-1342 
files, 1341 

routing information, 1341 
socket information, 
1340-1341 


network byte order, convert¬ 
ing between host byte order, 
901-902 

network entries, getting, 
936-937 
networking 

displaying active 
connections, 1339-1342 
routing information, 1341 
socket information, 
1340-1341 
interfaces 

attaching to serial line 
1399 

configuring, 1304-1305 
routing daemon, 1380-1382 

newaliases, 336 
newer (ftp command), 150 
newgrp, 336-337 
news 

N etnews, see tin 
news software information 
newsgroups, 530 
overview database 
erpiring entries 
1293-1294 
format, 1168-1169 
updating, 1353-1354 
receiving from UUCP 
connections, 463-464 
news.daily, 1344-1346 
keywords, 1344-1345 
newsfeeds, 1158-1163 
Distribution headers, 1159 
entries, 1158-1159 
examples, 1162-1163 
feed types, 1161-1162 
flags, 1159-1161 
M E entry, 1161 
newsgroups 

news software information, 
530 

U senet, listing active, 1104- 
1105 

newslog, 1163-1165, 
1346-1347 

files, 1164 
keywords, 1346 
messag^action fields, 


1163-1164 

newsrequeue, 1342-1344 
NFS 

mount daemon, 1332-1333 
servers, authentication/print 
request, 1355-1357 
service daemon, 1347 

nfs, 1165-1167 
nfs filesystem, 1125 
export list, 1123-1125 
NFS servers, mount 
information, 1396 
nfsd, 1347 
nice, 814 

nl, 337-338 

nlist (ftp command), 150 
NLM outfiles, converting 
object code into, 338-339 
nlmconv, 338-339 

nm, 339-340 

nmap (ftp command), 150 
nnrp.access, 1167-1168 
nnrpd, 1347-1349 
NNTP 

news, host list, 1132-1133 
servers, 1347-1349 

getting lists from, 206-207 
passwords 1110 
retrieving Usenet articles 
from, 340-341 
sites, access control, 
1167-1168 

N NT Pcheckartide routine, 
965 

NNTPconnect routine, 965 
nntpget, 340-341 
NNTPIocalopen routine, 965 
NNTP remoteopen routi ne, 

965 

nntpsend, 1349-1350 
nntpsend.ctl, 1168 
NNTPsendartideroutine, 966 
NNTPsendpassword routine, 

966 

NNTPSERVER environment 
variable, 529 






no_ exit_ o n_ fai I ed_ exec 
variable (bash), 18 
nodobber variable (bash), 18 
nolinks variable (bash), 18 
nologin, 1168 
none, 881 

none (undocumented library 
functions), 1060 
not-a-number (NaN) results 

returning value for, 954-955 
testing for, 959 

notify variable (bash), 17 
nrand48() functions, 912 
nroff 

emulating, 210-211 
output, filtering, 77 
nslookup, 1350-1353 

arguments, 1350 
commands, 1351-1353 
diagnostics, 1353 
environment, 1353 
files, 1353 

ntohl() function, 901-902 
ntohs() function, 901-902 
ntrans (ftp command), 
150-151 
null, 1094 
numbers 
floating-point 
absolute value, 919 
converting to fractional/ 
integral components, 

927 

converting to strings 
913-914, 930-931 
pseudo-random, generating, 
912-913 

random, generating, 
1001-1002 
rounding, 1011-1012 
signs, copying, 907 
square roots, 1023 
numeric expressions, gtroff, 
239 


papers formatting 
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objcopy, 341-342 
objdump, 342-343 
object files 

copying/translating, 

341- 342 

discarding symbols from, 

499 

displaying information from, 

342- 343 

listing section and total sizes, 
489-490 

listing symbols from, 
339-340 

odock, 344 
od, 345-346 

offline printing, 299-301 
oldfstat, 814 
oldlstat, 814 
oldolduname, 814 
OLDPWD variable (bash), 15 
oldstat, 814 
olduname, 814 
on_exit() function, 988 
open, 815-816 
bugs, 816 
errors, 816 
flags, 815 
ftp command, 151 
modes, 815 
return value, 816 
open host command (telnet), 
508 

opendir, 989 
openlog() function, 
1045-1046 

facility argument, 1046 
option argument, 1046 
operators 
awk, 166-167 
find, 142 
redirection, 21 

OPTARG variable (bash), 16 
OPT ERR variable (bash), 17 
OPTIND variable (bash), 16 


ORGANIZATION environ¬ 
ment variable, 529 
OSTYPE variable (bash), 16 
outb, 816 
outb p, 816 
outl, 816 
outlp, 816 
output 

formatting, 992-996, 
1022-1023 

conversion specifiers 994 
examples 995 
flags 993-994 
redirecting, 22 

output-meta variable 
(readline), 28 
outsb, 816 
outsl, 816 
outsw, 816 
outw,816 
outw p, 816 
overchan, 1353-1354 
overview.fmt, 1168-1169 
ownership (file), changing, 
62-63, 749-750 

P 


pac, 1354-1355 
packed format fonts, convert¬ 
ing to portable bitmaps, 381 
packets 

ECHO_REQUEST, 
sending, 1358 
route, printing, 1409-1412 

page size, system (getting), 
765 
paging 

disabling, 796-797 
calling process 797-798 
reenabling, 811-813 
papers, formatting 
groff_me macros, 

1225-1227 
groff_mm macros, 
1227-1234 
groff_ms macros, 

1234-1236 
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paragraphs, formatting line 
length, 143 

parameter command substitu¬ 
tion (bash), 20 
parameter expansion (bash), 
19-20 
parameters 
bash, 14-15 
positional, 14 
pedal, 14-15 
boot-time (kernel), 

1216-1224 
Adaptec configurations 
1219-1220 

argument list, 1216-1217 
B ui ogic configuration, 
1220 

busmouse drivers 1224 
cards not accepting, 1220 
CD-ROMs 1222-1223 
debug argument, 1217 
Ethernet da/ices, 1223 
floppy did< drives 
1223-1224 
future domain 
configuration, 1220 
hard <M$ 1220-1221 
mem= argument, 1218 
no-hit argument, 1217 
no387 argument, 1217 
Pro A udio configuration, 
1220 

ramdisk= argument, 1218 
reboot=warm argument, 
1218 

reserve= argument, 

1217- 1218 

ro argument, 1217 
root= argument, 1217 
rw argument, 1217 
SCSI da/ice arguments 

1218- 1219 

SCSI tape configuration, 
1219 

Seagate ST-Ox 
configuration, 1220 


sound drivers 1224 
T rantor T128 
configuration, 1220 
floppy disk, setting, 1391 
positional 
parsing, 38 
renaming, 42 
serial ports, 1392-1394 
parsedate, 989-990 
parser directives, readline, 
28-29 
$else, 29 
$endif, 29 
$if, 28-29 
parsing 

command options, 207-208 
command-line options, 
937-940 

positional parameters, 38 

partition tables, manipulat¬ 
ing, 1296-1297 
DOS 6.x, 1296-1297 
partitioning disk drives, 
1265-1269 

passwd, 346-347,1169-1170 

bugs, 347 
files, 347 

passwd.nntp, 1170 
password files, editing, 
1418-1419 
passwords 

changing, 346-347 
encryption, 908-909 
file entries, writing, 997 
getting, 940-941 
getting file entry, 943-944 
password file, 1169-1170 
reconstructing line entry, 
942-943 
paste, 347 

PATH variable (bash), 16 
pathconf() function, 925-926 

options returned, 926 
return value, 926 

pathname expansion (bash), 
21 


pathnames 

canonicalized absolute, 
1004-1005 

following to terminal point, 
335-336 

matching, 924, 949-950 

patterns 

printing lines matching, 
224-226 

searching database files for, 
295 

pause, 817 

pausing execution, 813-814 
pbm, 1170-1171 
PBM images, displaying on 
4425 terminals, 357 
pbmdean, 348 
pbmfilters, 348-352 
pbmlife* 352-353 
pbmmake, 353 
pbmmask, 353-354 
PBM Plus package, programs, 
348-352 
pbmpscale, 354 
pbmreduce, 355 
pbmtext, 355-356 
pbmtolOx, 356 
pbmto4425, 357 
pbmtoascii, 357 
pbmtoatk, 358 
pbmtobg, 358 
pbmtocmuwm, 358-359 
pbmtoepsi, 359 
pbmtoepson, 359 
pbmtog3, 360 
pbmtogem, 360 
pbmtogo, 360-361 
pbmtoicon, 361 
pbmtolj, 361-362 
pbmtoln03,362 
pbmtolps, 362 
pbmtomacp, 363 
pbmtomgr, 363 
pbmtopgm, 364 
pbmtopi3, 364 
pbmtopk, 364-365 
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pbmtoplot, 365-366 
pbmtoptx, 366 
pbmtoxlObm, 366 
pbmtoxbm, 367 
pbmtoybm, 367 
pbmtozinc, 367-368 
pbmupc, 368 
pd09e(), 991-992 
pcnfsd, 1355-1357 

authentication, 1355-1356 
file, 1357 
printing, 1356 
reconfiguration, 1357 
PCX files, converting to 
portable pixmaps, 368-369 
pcxtoppm, 368-369 
peers, getting names, 765 
permissions 
file 

changing, 748-749 
setting, 272-273 
port input/output, setting, 
788 

perror, 990-991 
personality, 817-818 
pfbtops, 369 
pgm, 1171-1172 
pgmbentley, 369 
pgmcrater, 370-371 
pgmedge, 371 
pgmenhance, 371-372 
pgmhist, 372 
pgmkernel, 372-373 
pgmnoise, 373 
pgmnorm, 373-374 
pgmoil, 374 
pgmramp, 374-375 
pgmtexture, 375-376 
pgmtofs, 376 
pgmtolispm, 376-377 
pgmtopbm, 377 
pgmtoppm, 378 
Photo-C D files, converting to 
portable pixmaps, 260-261 
phys, 818 

physical addresses, accessing, 
818 


pi3topbm, 379 

pic, versus gpic, 212-215 

commands, 212-213 
expressions, 213-214 
mode, 212 

picttoppm, 379-380 

bugs, 379 

fontdir fileformat, 380 

ping, 1358 
pipe, 818-819 
pipelines (|), bash, 12 
pipes, creating, 818-819 
pjtoppm, 381 
pktopbm, 381 
PLIP devices, tuning 
parameters, 1357 
plipconfig, 1357 
pnm, 1173 
pnmalias, 381-382 
pnmarith, 382-383 
pnmcat, 383 
pnmcomp, 383-384 
pnmconvol, 384 
pnmcrop, 385 
pnmcut, 385 
pnmdepth, 385-386 
pnmenlarge, 386 
pnmfile, 386-387 
pnmflip, 387 
pnmgamma, 387 
pnmhistmap, 388 
pnmindex, 388-389 
pnminvert, 389 
pnmmargin, 389-390 
pnmnlfilt, 390-391 

alpha-trimmed mean filter, 
390 

bugs, 391 

combining modes, 391 
edge enhancement, 391 
optimal estimation 
smoothing, 390 

pnmnoraw, 391-392 
pnmpad, 392 
pnmpaste, 392-393 
pnmrotate, 393 


pnmscale, 393-394 
pnmshear, 394-395 
pnmsmooth, 395 
pnmtile, 395 
pnmtoddif, 396 
pnmtofits, 396-397 
pnmtoiff, 399-400 
pnmtopsi 397 
pnmtorast, 398 
pnmtosgi, 398-399 
pnmtosir, 399 
pnmtoxwd, 400 
popd (shell command), 39-40 
popen() function, 991-992 
popup-menu() action 
(xterm), 713 
port, 1091-1092 
portable anymaps 
antialiasing, 381-382 
bordering, 389-392 
changing maxval, 385-386 
compositing, 383-384 
concatenating, 383 
converting 

toDDIF format, 396 
to FITS format, 396-397 
to PostScript, 397 
to red/blue 3D glasses, 
400-401 
to SGI image file 
398-399 

to Solitaire format, 399 
to Sun raster files 398 
to TIFF files 399, 400 
toXll window dumps 
400 

convolving, 384 
creating index of, 388, 389 
cropping, 385 

cutting rectangles from, 385 
describing, 386, 387 
drawing histograms from, 
388 

enlarging, 386 
fileformat, 1173 
flipping, 387 
gamma correction, 387 
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inverting, 389 

pasting rectangles into, 392, 
393 

performing arithmetic on, 
382, 383 

plain format, 391, 392 
programs 
constants 970 
format promotion, 912 
functions supporting, 970, 
971, 972 
initialization, 971 
memory management, 971 
reading files 971 
types, 970 

writing files, 971, 972 
XEL manipulations 
971-972 

replicating into specified 
size, 395 
rotating, 393 
scaling, 393, 394 
shearing, 394, 395 
smoothing, 395 
portable bitmaps 

applying Rules of Life to, 
352, 353 
converting 

to Andrew Tootkit raster 
objects 358 
to ASCI I graphics 357 
to Atari DegasP13 files, 
364 

to Ben net Yee “face" files 
367 

to BitGraph graphics 358 
to CM U window manager 
bitmaps 358-359 
to compressed G raphO n 
graphics 360-361 
to DEC LN03+Sixd 
output, 362 

to encapsulated PostScript- 
style bitmaps 359 
to Epson printer graphics 
359 


to GEM IMG files 360 
to Gemini 1 Ox graphics 
356 

to Group 3 fax files 360 
to HP LaserJet format, 
361-362 

to M acPaint files 363 
to MGR bitmap, 363 
to packed format fonts 

364- 365 

to portable graymaps 364 
to PostScript, 362 
to Printronix printer 
graphics 366 
to Sun icons 361 
to UN IX plot files 

365- 366 

toXlO bitmaps 366 
toXll bitmaps 367 
to Zinc bitmaps 367-368 
creating with specified size, 
353 

enlarging, 354 
fileformat, 1170-1171 
flipping pixels in, 348 
programs 
constants, 968 
endian i/o, 967 
errors 967 

file management, 967 
functionssupporting, 
966-969 

initialization, 968 
keyword matching, 967 
memory management, 968 
messages 967 
reading files 968 
types 968 

writing files 968-969 
reducing, 355 
portable graymaps 
Bentleyizing, 369 
calculating textural features 
on, 375-376 
combining three into a 
portable pixmap, 457-458 


converting 

to L isp machine format, 
376-377 

to portable bitmaps 377 
to portablepixmaps 378 
toUsenixFaceSaver 
format, 376 

creating from white noise, 

373 

enhancing edges, 371-372 
fileformat, 1171-1172 
mimicking cratered terrain, 
370-371 

normalizing contrast, 
373-374 

outlining edges, 371 
performing oil transfers on, 

374 

printing histogram of values, 
372 

programs 
constants, 969 
functionssupporting, 
969-970 

initialization, 969 
memory management, 969 
reading files 970 
types 969 
writing files 970 
portable pixmaps 

blending together, 408-409 
brightening, 404 
changing pixel color, 
401-402 

changing saturation and 
value, 401 
converting 

toAbekasYUV files, 428 
to Atari DegasPIl files, 
422 

to AutoCAD, 414-416 
to BMP files 416 
to DEC axel format, 
425-426 

to GIF files 416-417 
to HP PaintJet files 423 
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to HP PaintJet XL PCL 
files, 424 

tolLBM files, 418-419 
to M acintosh PICT files, 
422-423 

toM itsubishi 5340-10 
files, 420-421 
toM otifillL icon files 
427 

to NCSA ICR format, 
417-418 
to PCX files 421 
to portable graymaps 
421-422 

to three portable graymaps 

425 

to three raw YU V files 
428-429 

to Trud/ision Targa files 

426 

toXll pixmaps 427-428 
toXll puzzle files 
424-425 
creating, 408 
patterns 410-411 
Specifying color, 408 
creating from three portable 
graymaps, 457-458 
dimming 
to black, 402 
e/ery other row, 409-410 
displacing pixels, 414 
dithering, 403 
extracting color from, 
419-420 

fileformat, 1173-1174 
files 

reading, 974 
writing, 974 

fractal forgeries, 404-407 
grayscale assignments 
(performing), 402-403 
histograms (printing), 408 
Laplacian relief filters 
(running on), 413 
normalizing contrast, 409 


programs, functions 
supporting, 973-974 
quantizing colors, 411 
8-planequantization, 
412-413 

multi pie files 412 
shifting lines, 413-414 

portmap, 1358-1359 
ports 

input/output functions, 816 
input/output permissions, 
setting, 788 
serial 

configuring, 1394-1395 
parameters, 1392-1394 
satting/getting informa¬ 
tion, 1391-1395 
system, 1091-1092 
positional parameters 
bash, 14 
parsing, 38 
renaming, 42 
POSIX 

gawk compatibility, 171 
regex functions, 1005-1007 
compiling, 1005-1006 
error reporting, 1006 
matching, 1006 
pattern buffer freeing, 
1007 

signal set operations, 
1019-1020 

PostScript 

bounding box, extracting, 
433 

files, converting to portable 
anymaps, 434-435 
fonts 

translating from PFB 
format to ASCII, 369 
translating fromPFB 
format to ASCII, 369 
image data, converting into 
portable graymap, 

433-434 
pound sign (#) 
bash comments, 14 
bash special parameters, 15 


pow() function, 918 
powerd, 1359-1360 
powers (raising numbers to), 
918 

PPID variable (bash), 15 
ppm, 1173-1174 
ppm3d, 400-401 
ppmbrighten, 401 
ppmchange, 401-402 
ppmdim, 402 
ppmdist, 402-403 
ppmdither, 403 
ppmflash, 404 
ppmforge, 404-407 
bugs, 407 
options, 405-407 
ppmhist, 408 
ppmmake, 408 
ppmmix, 408-409 
ppmnorm, 409 
ppmntsc, 409-410 
ppm pat, 410-411 
ppmquant, 411-412 
ppmquantall, 412 
ppmqvga, 412-413 
ppmrelief, 413 
ppmshift, 413-414 
ppmspread, 414 
ppmtoacad, 414-416 
ppmtobmp, 416 
ppmtogif, 416-417 
ppmtoicr, 417-418 
ppmtoilbm, 418-419 
ppmtomap, 419-420 
ppmtomitsu, 420-421 
ppmtopcx, 421 
ppmtopgm, 421-422 
ppmtopil, 422 
ppmtopict, 422-423 
ppmtopj, 423 
ppmtopjxl, 424 
ppmtopuzz, 424-425 
ppmtorgb3,425 
ppmtosixel, 425-426 
ppmtotga, 426 
ppmtouil, 427 
ppmtoxpm, 427-428 
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ppmtoyuv, 428 
ppmtoyuvsplit, 428-429 
PPP 

daemon, 1360-1369 
statistics, printing, 
1369-1370 

pppd, 1360-1369 

authentication, 1366-1367 
diagnostics, 1368 
examples, 1367-1368 
files, 1366-1369 
options, 1360-1366 
routing, 1367 
signals, 1369 
pppstats, 1369-1370 
pr, 429-430 
preprocessor, 81-84 
preprocessors, imake, 264-267 
printf function, 992-996 
bugs, 995-996 
printf statement, awk, 

167-168 
printing 
aliases, 35 

application resources, 5 
banners, 1210 
converting text files for, 
429-430 

files, in reverse, 503-504 
histograms of portable 
pixmaps, 408 
host IDs, 258-259 
lines matching a pattern, 
224-226 

log messages (RCS files), 
458-460 

machine architecture, 8 
offline, 299-301 
packet route, 1409-1412 
pcnfsd, 1356 
PPP statistics, 1369-1370 
printer/plotter accounting 
files (reading), 1354-1355 
removing jobs from queue, 
301-302 

ripple test pattern, 302 
signal messages, 996 


spool queue examination, 
298-299 

system activity summary, 
573 

system error messages, 

990- 991 

time zones, 1419 
user/system times, 43 
seea/so line printer 

priority values, getting range, 
830-831 
privileges 

I/O, changing level, 

788-789 

setuid (RCS files), 67-68 

/ proc, 1174-1180,1236 

bugs, 1180 

hierarchy outline, 1174- 
1180 

proc filesystem, 1125 
procsel, 1430-1431 
process control, initialization, 
1307-1309,1397-1399 
process groups, sending 
signalsto, 790-791,960 
process substitution (bash), 

20 

processes 

0, making idle, 774 
accounting, switching on/ 
off, 742 

child, creating, 751, 758 
closing, pclose() function, 

991- 992 

displaying tree of, 435-436 
execution, suspending, 1061 
execution domain, setting, 
817-818 

group identity, setting, 845 
group IDs 

getting/setting, 845-846 
real and effective (setting), 
846-847 
groups 

access lists (getting/setting), 
761-762 

IDs(getting), 761 


identifying, 154-155 
IDs, getting, 766 
listing most CPU-intensive, 
533-535 

opening, popenf) function, 
991-992 

parents, IDs (getting), 766 
priorities, altering, 
1375-1376 

priority, changing, 814 
reporting status, 430-433 
SCH ED_RR interval, 
getting, 831 
scheduling priorities, 
getting/setting, 766-767 
selecting, by criteria, 
1430-1431 

sending signalsto, 790 
raise function, 1000 
starting, on consoles, 1066 
terminating, 283-284, 
739-740 
byname 284 
times, getting, 878-879 
tracing, 820 
user ID s 
getting, 773 

real and effective (setting), 
847-848 
setting, 848-849 
waiting for termination, 
886-889 

yielding processor, 835 

processor, time used (deter¬ 
mining), 905 
profil, 819 
profiling, 819 
programs 

executing, 754-755 
portable anymap 
constants, 970 
format promotion, 972 
functions supporting, 
970-972 

initialization, 971 
memory management, 971 
reading files 971 





rawtoppm ■ 


types, 970 

writingfiles, 971-972 
XEL manipulations 
971-972 

portable bitmap, functions 
supporting, 966-969 
portable graymap 
constants 969 
functions supporting, 
969-970 

initialization, 969 
memory management, 969 
reading files 970 
types, 969 
writingfiles 970 
recompiling, make utility, 
310-312 

running, in new session, 
1395 

terminating 

abortf) function, 892 
asasrtf) function, 

895-896 

exit() function, 917 

promoting directories, 39-40 
prompt (ftp command), 151 
PROM PT COM MAND 
variable (bash), 17 
prompting (bash), 26 
properties, consoles, 1067 
protocols 

protocols definition file, 
1180-1181 

RPC, rpcgen compiler, 
464-466 

Telnet, interface, 507-512 
XIE, testing, 645-654 

proxy ftp (ftp command), 151 
proxy servers, LBX, 286-287 
PRT ray tracers, converting 
output to portable pixmaps, 
333 

prunehistory, 1370-1371 
ps, 430-433 

bugs, 433 

field descriptions, 432 
options, 430-431 



sort keys, 431-432 
updating, 432, 436 

PS1 variable (bash), 16 
PS2 variable (bash), 16 
PS3 variable (bash), 17 
PS4 variable (bash), 17 
psbb, 433 

pseudo-filesystems, / proc, 
1174-1180 

bugs, 1180 
hierarchy outline, 
1174-1180 

pseudo-random numbers, 
generating, 912-913 
psidtopgm, 433-434 
pstopnm, 434-435 
pstree, 435-436 
psupdate, 436 
ptrace, 820 

pushd (shell command), 40 
put (ftp command), 151 
putfilelast, 1431 
putc() function, 997-999 
putchar() function, 997-999 
putenv, 996-997 
errors, 996 

putpwent() function, 997 

errors, 997 

puts() function, 997-999 
pututline() function, 948 
putw function, 948 
pwd (ftp command), 151 
pwd (shell command), 40 
PWD variable (bash), 15 

Q 


qio, 998 

QRT ray tracer, converting 
output to portable pixmaps, 
436-437 
qsort, 1000 

quantizing colors (pixmaps), 
411 

8-plane quantization, 
412-413 

multiple files, 412 


question marks (?) 

bash special parameters, 15 
ftp command, 152 

queues, inserting/removing 
items, 957 
quit command 

ftp command, 151 
telnet, 508 
xauth, 591 

quit() action (xterm), 714 
quota, 437 

quotacheck, 1371-1372 
quotactl, 821-822 
quotaoff, 1372-1373 
quotaon, 1372-1373 
quotas 

disk, manipulating, 821-822 
remote machines, 1012 

quote (ftp command), 151 
quoting (bash), 14 

R 

Radix32 routine, 966 
raise function, 1000 
ram, 1094-1095 
rand() function, 1001 
random numbers, generating, 
1001-1002 

RANDOM variable (bash), 15 
random() function, 
1001-1002 

randomizing strings, 1032 
ranlib, 437-438 
rarp, 1373 

RARP table, manipulating, 
1373 

rasttopnm, 438 
raw grayscale bytes, convert¬ 
ing to portable graymaps, 
439 

raw RGB bytes, converting to 
portable pixmaps, 439-440 
rawtopgm, 439 
rawtoppm, 439-440 
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ray tracers 

converting output to 
portable pixmaps, 333 
Q RT, converting output to 
portable pixmaps, 436-437 

rep, 440-441 
RCS (Revision Control 
System), 447-449 

automatic identification, 

449 

commands, 447-449 
directories, creating, 

447-449 

files 

changing attributes, 
441-443 

cleaning, 443-445 
comparing revisions 

445- 446 

freezing configuration, 

446- 447 
functions, 447 

revisions, merging, 449-451 
res, 441-443 
bugs, 443 
compatibility, 443 
diagnostics, 443 
environment, 443 
files, 443 
options, 441-443 
RCS files 

controlling access, 67 
format, 1181-1183 
modes, 67 

organization (diagram), 

1182 

printing log messages, 
458-460 

retrieving revisions, 71-75 
specifying, 66-67 
storing revisions, 64-69 
stuid privileges 67-68 
temporary files, 67 
RCS keyword strings, 
identifying, 262-263 
RCSBIN environment 
variable, 105 


rcsclean, 443-445 
resdiff, 445-446 
resfile, 1181-1183 

organization (diagram), 
1182 

resfreeze, 446-447 
rcsintro, 447-449 

automatic identification, 
449 

RCS functions, 447 

resmerge, 449-451 
rdev, 1373-1375 
rdiff (evs command), 101 
rdist, 451-454 
bugs, 454 
diagnostics, 454 
files, 453 
options, 451-452 
re comp function, 1005 
reexec function, 1005 
read (shell command), 40 
read(), file descriptors, 822 
readdir, 823 
readdir() calls, setting 
position, 1015-1016 
readdir() function, 
1002-1003 

ReadlnD escriptor routine, 
966 

ReadlnFiie routine, 966 
readline library, 27-32 

commands, 29-32 
controlling key bindings, 27 
customizing, 27 
denoting keystrokes, 27 
macro definitions, 28 
parser directives, 28-29 
$e/se, 29 
$endif, 29 
$if, 28-29 
variables, 28 
bell-style 28 
comment-begin, 28 
completion-query-items 
28 

convert-meta, 28 
editing-mode 28 
apand-tilde, 28 


horizontal-ssroll-mode 28 
keymap, 28 

mark-modi fied-lines, 28 
meta-flag, 28 
output-meta, 28 
show-all-if-ambiguous 28 

readlink, 823-824 
readonly (shell command), 40 
readv, 824-825 
readv() function, 1003-1004 
realloc() function, 976-977 
realpath, 1004-1005 
reboot, 825-826 
recompiling programs, make 
utility, 310-312 
recompressing Z files, 

734-735 
reconfig, 454 
reev, 151, 826-828 
recvfrom, 826-828 
recvmsg, 826-828 
redirection, 21-23 

duplicating file descriptors, 
23 

here-documents, 22-23 
input, 22 

opening file descriptors, 23 
operators, 21 
output, 22 

redraw() action (xterm), 714 
ref, 455-456 

elvis interaction, 455 
environment, 455 
files, 455 
options, 455 
search method, 455 
refreshing screen (X), 684-685 
refs files, generating, 87-88 
regcomp function, 1005-1007 
regerror function, 1005-1007 
reget (ftp command), 151 
regex functions, 1005 
POSIX, 1005-1007 
compiling, 1005-1006 
error reporting, 1006 
matching, 1006 
pattern buffer freeing 
1007 
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regexec function, 1005-1007 
regfree function, 1005-1007 
regular expressions 

grep, 225-226 
sed, 476-477 

release (cvs command), 101 
remote execution server, 

1376- 1377 

remote file copying, 440-441 
remote logging, 1403 
remote login server, 

1377- 1378 

remote logins, 460-461 

Kerberos authentication, 

461 

remote machines, starting X 
programs on, 676 
remote quota server, 1384 
remote shell, 466-467 
remote shell server, 

1385-1386 

Remote Start client, see rstart 
Remote Start rsh helper, see 
rstartd 

remote status, displaying, 472 
remote systems, command 
execution, 569-571 
remote user communication 
server, 1405-1406 
remotehelp (ftp command), 
151 

remotestatus (ftp command), 
151 

remove, 1008 

cvs command, 101-102 
xauth command, 591 

removefilefree, 1431-1432 
remque() function, 957 
rename, 828-829 
rename (ftp command), 151 
renice, 1375-1376 
REPLY variable (bash), 15 
REPLYTO environment 
variable, 529 
repquota, 1376 
resinit, 1008-1011 



resmkquery, 1008-1011 
resquery, 1008-1011 
res search, 1008-1011 
res" send, 1008-1011 
reserved words (bash), 12 
reset, 456, 539-542 
compatibility, 542 
options, 540 

setting environment, 540 
terminal type mapping, 
540-541 

reset (ftp command), 151 
resize, 456-457 
resolver, 1183-1184 
resolver routines, 1008-1011 
resolving hostnames, 
1238-1239 

resource editor, see editres 
resources 

limits, getting/setting, 
767-768 

usage, getting, 767-768 

restart (ftp command), 151 
return (shell command), 40 
return value, errors, 797 
rev, 457 

reverse line feeds, filtering, 76 
Revision Control System, see 
RCS 

rewind function, 927-928 
rewinddir() function, 1011 
rexecd, 1376-1377 
bugs, 1377 
diagnostics, 1377 
protocol, 1376-1377 
RGB colornamedatabases, 
uncompiling, 488 
rgb3toppm, 457-458 
rindex() function, 953 
rint() function, 1011-1012 
rippletest pattern (printing), 
302 

rlog, 458-460 
rlogin, 460-461 
rlogind, 1377-1378 
rm, 461-462 


rmdir, 462, 829-830 

bugs, 830 
errors, 829 
options, 462 

rmdir (ftp command), 152 
rmmod, 462-463 
rnews, 463-464 
Rock Ridge filesystem, 1125 
root logins, tty lines (listing), 
1184 

root directories 

changing, 750-751,1273 

root filesystem, mounting, 
849 

root window (X), setting 
parameters, 693-694 
round-robin scheduling, 834 
rounding integers, 904 
rounding numbers, 
1011-1012 
route, 1379-1380 
routed, 1380-1382 
bugs, 1382 
files, 1382 

gateways, 1381-1382 
options, 1381 
request packets, 1381 
response packets, 1381 
starting, 1380 
routines 

ICCcancel, 956 
ICCdose, 956 
ICCcommand, 956 
ICCgo, 956 
ICCopen, 956 
ICC pause, 956 
IC C reserve, 956 
ICCsettimeout, 956 
libinn library, 962-966 
CAdose, 964 
CAIistopen, 964 
C A open, 964 
Clo^OnExec, 965 
DD check, 965 
DDend, 965 
DD start, 965 
GetConfigValue, 965 
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GetFileConfigValue, 965 
GetFQDN, 965 
GetM oderatorAddress 
965 

GetResjurceU sage, 965 
GetTimelnfo, 965 
H eaderFind, 964 
INN Version, 966 
LockFile, 965 
N NTPcheckartide 965 
NNTPconnect, 965 
NNTPIocalopen, 965 
N NTPremoteopen, 965 
N NTPsndarticle, 966 
NNTPsndpamord, 966 
Radix32, 966 
Readln Descriptor, 966 
ReadlnFilet 966 
SetN onBlocking, 965 
libpbm, 966-969 
constants 968 
endian i/o, 961 
errors 967 

file management, 967 
initialization, 968 
keyword matching, 967 
memory management, 968 
messages, 967 
reading files 968 
types 968 

writing files, 968-969 
libpgm, 969-970 
constants 969 
initialization, 969 
memory management, 969 
reading files 970 
types, 969 
writing files, 970 
libpnm, 970-972 
constants 970 
format promotion, 972 
initialization, 971 
memory management, 971 
reading files 971 
types, 970 

writingfiles, 971-972 
XEL manipulation, 972 
XEL manipulations 971 


routing, pppd, 1367 
RPC 

program numbers, 
converting to D ARPA port 
numbers, 1358-1359 
protocol compiler, seerpcgen 
services, reporting informa¬ 
tion, 1383-1384 
rpc.rquotad, 1384 
rpc.rusersd, 1382-1383 
rpc.rwalld, 1383 
rpcgen, 464-466 
options, 465-466 
preprocessor symbols, 465 
rpcinfo, 1383-1384 
rquota() protocol, 1012 
rquotad, 1384 
rsh, 466-467 
rshd, 1385-1386 
rstart, 467-468 
rstartd, 468-471 
configuring, 469 
keywords 470 
installing, 469 
options, 469 

rtag (cvs command), 102 

runique (ftp command), 152 

rup, 472 

rusers, 472-473 

rwall, 473 

rwho, 474 

rwhod, 1386-1387 

s 


saving stack context, 1018 
/sbin directory, 1237 
sbrk, 746 

scandirf) function, 
1012-1013 

scanf functions, 1013-1015 

bugs, 1015 

conversions, 1014-1015 
flags, 1014 
return values, 1015 

sched get priority max, 
830“83l” 


sched get priority min, 
830-83l" 

sched getparam, 832 
sched getscheduler, 833-835 

errors, 834 
policies, 833 

SCHED_FIFO, 833-834 
SCH ED_OTH ER, 834 
SCHED_RR, 834 
response time, 834 

schedrrgetinterval, 831 
schedsetparam, 832 
sched setscheduler, 833-835 

errors, 834 
policies, 833 

SCHED_FlFO, 833-834 
SCH ED_OTH ER, 834 
SCHED_RR, 834 
response time, 834 

sched yield, 835 
scheduling 

algorithm, getting/setting, 
833-835 

parameters, getting/setting, 
832 

policies, 833 
first in - first out, 

833-834 
round-robin, 834 
timesharing, 834 
priorities 

getting/setting, 766-767 
value ranges 830-831 
yielding processor, 835 

screen, clearing, 70-71 
screen savers, beforelight, 
47-48 

script, 474-475 
scripts, chat, 1270 
scroll-back() action (xterm), 
714 

scroll-forw() action (xterm), 
714 

SCSI drivers 

disk drives, 1095-1096 
tape devices, 1096-1100 

sd, 1095-1096 
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searching 

binary trees, 1056 
strings, for character sets, 
1035-1039 

second extended filesystems 

creating, 1324-1325 
lost+found directory, 1327 
tunable parameters 
(adjusting), 1412-1413 

SEC 0 N D S variable (bash), 15 
secure() action (xterm), 713 
securetty, 1184 
security 

sysklogd, 1403-1404 
X server, 688-689 
xterm, 712 

sed, 475-480 

addresses, 476 
bugs, 480 

commands, 478-479 
grouping, 478 
syntax, 476 
comments, 477 
diagnostics, 479-480 
options, 475 

regular expressions, 476-477 
replacement pattern 
symbols, 477 
search pattern symbols, 
476-477 

seed48() functions, 912 
seekdir() function, 

1015-1016 
select, 835-837 
select-cursor-end action 
(xterm), 714 

select-cursor-start() action 
(xterm), 714 

select-end() action (xterm), 
714 

select-extend!) action 
(xterm), 714 

select-start() action (xterm), 
714 

selections, copying into cut 
buffers, 598-599 



semaphore sets 

control operations, 837-839 
GET ALL, 838 
GETNCNT, 838 
GETPID, 838 
GETVAL, 838 
GETZCNT, 838 
IPC_RM ID, 838 
IPCJET, 838 
IPCJTAT, 837 
SET ALL, 838 
SETVAL, 838 
identifiers (getting), 
839-840 

operations, 840-842 

semctl, 837-839 

errors, 838-839 
operations, 837-838 
GET ALL, 838 
GETNCNT, 838 
GETPID, 838 
GETVAL, 838 
GETZCNT, 838 
IPC_RM ID, 838 
IPCJET, 838 
IPCJTAT, 837 
SET ALL, 838 
SETVAL, 838 
semget, 839-840 
semop, 840-842 
send, 842-843 
ftp command, 152 
send arguments command 
(telnet), 508-509 
send-signal() action (xterm), 
714 

sendmail, 1387-1390 

aliases, 1390 
exit status codes, 1390 
files, 1390 
flags, 1388 
options, 1389-1390 
sendmsg, 842-843 
sendport (ftp command), 152 
sendto, 842-843 
serial lines 

monitoring, 1359-1360 
network interfaces, 
attaching, 1399-1401 


serial mouse interface, 
1092-1094 

M icrosoft protocol, 1093 
M M protocol, 1094 
M ouseSystems protocol, 
1093 

Sun protocol, 1093 

serial ports 

configuring, 1394-1395 
parameters, 1392-1394 
setting/getting information, 
1391-1395 

serial terminal lines, 1101 
servers 

biff, 1274-1275 
controlling with xdm, 
612-613 

DARPA FTP, 1301-1304 
requests supported, 
1302-1303 

DARPA T el net protocol, 
1406-1407 
DARPA TFTP, 1407 
domain 

looking up hostnames 
with, 257-258 
resolver routines 
1008-1011 
font (X) 

diqolaying information 
about, 145 
generating BD F fonts 
146-147 

listing fonts 145-146 
interned atoms, listing, 
668-669 

Internet, xinetd (starting 
with), 655-664 
Internet domain nameserver, 
1334-1338 
boot file 1334-1336 
control interface, 
1338-1339 
master file, 1336 
querying, 1350-1353 
signals 1337 
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SOA record, 1336-1337 
stopping/restarting, 1338 
9 /nchronizing database, 
1338 

I nternet superserver, 
1305-1307 

LBX proxy server, 286-287 
logged-in users, 1382-1383 
news, sending U senet 
articles to, 267-269 
NFS 

authentication/print 
request, 1355-1357 
mount information, 1396 
NNTP, 1347-1349 

getting lists from, 206-207 
passwords 1170 
retrieving U senet articles 
from, 340-341 
portmap, 1358-1359 
remote execution, 

1376-1377 

remote login, 1377-1378 
remote quota, 1384 
remote shell, 1385-1386 
remote user communication, 
1405-1406 

specifying, xdm, 607-608 
system status, 1386-1387 
message format, 
1386-1387 
X W indow System 
access control program, 
643-645 

display server, 685-690 
file utility, 587-592 
font server, 641-643 
information utility, 614 
killing clients 666-667 
starting, 664-666 
virtual framebuffer, 
717-718 
Xll 

performance comparison 
program, 585-586 
performance test program, 
577-585 


XF86_8514, 615 
XF86_Accel, 614-623 
configuration, 615-616 
files 622 
options 616 
setup, 616-622 
XF86_AGX, 615 
XF86_M ach32, 615 
XF86_Mach64, 615 
XF86_Mach8, 615 
XF86_M ono, 624-627 
configuration, 624 
files 626 
setup, 624-626 
XF86_P9000, 615 
XF86_S3, 615 
XF86_SVGA, 627-631 
configuration, 627-628 
files 630-631 
options 628 
setup, 628-630 
XF86_VGA16, 631-633 
configuration, 631 
files 633 
options 632 
setup, 632 
XF86_W32, 615 
XFree86, 636-641 
configuration, 636 
environment variables 
637 

files 638-639 
key combinations 638 
network connections 
636-637 
options 637-638 
setup, 638 

services, 1184-1186 

bugs, 1186 
files, 1186 

Internet, listing, 1184-1186 
N FS, daemon, 1347 
RPC, reporting information, 
1383-1384 

Session Manager Proxy, see 
sm proxy 


sessions 

creating, setsid, 848 
IDs, getting, 768 
typescripts, creating, 

474-475 

X Session M anager, 694-698 
default startup applica¬ 
tions 695 
options 695-698 
proxy, 698 

remote applications 698 
Session menu, 695-696 
SM _SAVE_D IR 
environment variable 
695 

starting, 695 
tester, 698-699 
.xsesaon file, 695 
xdm, 600 

sessreg, 480-481 
set 

shell command, 40-42 
telnet command, 509-510 

set-allowl32() action (xterm), 
715 

set-altscreen() action (xterm), 
715 

set-appcursor() action 
(xterm), 715 
set-appkeypad() action 
(xterm), 715 

set-autolinefeed() action 
(xterm), 715 
set-autowrap() action 
(xterm), 715 
set-cursesemul() action 
(xterm), 715 
set-jumpscroll() action 
(xterm), 715 
set-marginbell() action 
(xterm), 715 

set-reverse-video() action 
(xterm), 715 
set-reversewrap() action 
(xterm), 715 

set-scroll-on-key() action 
(xterm), 715 





set-scroll-on-tty-output() 
action (xterm), 715 
set-scrollbar() action (xterm), 
715 

set-tek-text() action (xterm), 
715 

set-terminal-type() action 
(xterm), 715 

set-visibility() action (xterm), 
715 

set-visual-bell() action 
(xterm), 715 

set-vt-font() action (xterm), 
714 

setbuf function, 1016-1017 
setbuffer function, 1016-1017 
setdomainname, 760 
setegid, 846-847 
setenv() function, 1017 
seteuid, 847-848 
setfdprm, 1391 
setfsgid, 843-844 
setfsuid, 844 
setgid, 845 

setgrent() function, 932-933 
setgroups, 761-762 
sethostid, 762-763 
sethostname, 763 
setitimer, 763-764 
bugs, 764 

defining values, 764 
errors, 764 
return value, 764 
timer types, 764 

setjmp() function, 1018 
setlinebuf function, 
1016-1017 
setlocale() function, 
1018-1019 

setmntent() function, 
935-936 

SetN on Blocking routine, 965 
setpgid, 845-846 
setpgrp, 845-846 
setpriority, 766-767 
setprotoent() function, 
941-942 
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setpwent() function, 943 
setregid, 846-847 
setreuid, 847-848 
setrlimit, 767-768 
setserial, 1391-1395 
configuration consider¬ 
ations, 1394-1395 
files, 1395 
options, 1392 
parameters, 1392-1394 
setservent() function, 946 
setsid, 848,1395 
errors, 848 

setsockopt, 769-772 

bugs, 772 
errors, 771 

options recognized, 770-771 
SO _BROAD CAST, 111 
SO_D EBUG, 770 
SO _D OUT ROUT E, 770 
SO ERROR, 771 
SOJEEPALIVE, 770 
SO_LINGER, 770 
SO_RCVBUF, 771 
SO_RCVLOWAT, 771 
SO_RCVTIM EO, 771 
SO_REUSEADDR, 770 
SO_SN D BUF, 771 
S0_SNDL0WAT, 771 
SO _SN DTIM EO, 771 
SO TYPE, 771 
return value, 771 
setstate() function, 

1001-1002 
setterm, 482-483 
settimeofday, 772-773 
setuid, 848-849 
setup, 849 

setusershelH) function, 
946-947 

setutent() function, 947 
setvbuf function, 1016-1017 
SGI image files, converting to 
portable anymaps, 483-484 
sgitopnm, 483-484 
sh, expansion, 19 


shadow directories (creating), 
294 

shar, 484-487 

files, unpacking, 560-561 
options, 484-486 

shared libraries, selecting, 883 
shared memory 

allocating, 851-853 
controlling, 849-851 
commands 850 
si/Stem calls 851 
operations, 853-854 
shell variables (bash), 15-18 
allow-null_glob_expansion, 
17 

auto_resume, 18 
BASH,15 

BASH_VERSIO N , 15 
cdable_vars, 18 
CD PATH, 16 
command_oriented_history, 

17 

ENV, 16 
EUID,15 
FCEDIT, 17 
FIGNORE, 17 
glob_dot_filenames, 17 
histchars, 17-18 
H ISTCM D, 16 
HISTFILE, 17 
HISTFILESIZE, 17 
history control, 17 
HISTSIZE, 17 
HOM E, 16 

hostname_completion_file, 

18 

HOSTTYPE, 16 
IFS, 16 

IGNOREEOF, 17 
INPUTRC, 17 
LINENO, 15 
MAIL, 16 

M AIL_WARN IN G, 16 
MAILCHECK, 16 
M AILPATH, 16 
no_exit_on_failed_exec, 18 
noclobber, 18 
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nolinks, 18 
notify, 17 
OLDPWD, 15 
OPTARG, 16 
OPTERR, 17 
OPTIND, 16 
OSTYPE, 16 
PATH, 16 
PPID, 15 

PRO M PT_CO M M AN D, 
17 

PS1,16 
PS2,16 
PS3,17 
PS4,17 
PWD, 15 
RANDOM , 15 
REPLY, 15 
SECONDS, 15 
SH LVL, 15 
T M 0 UT, 17 
UID,15 
shells 

archives, creating, 484-487 
Bourne-again, 11-46 
aliases 23-24 
arguments, 11 
arithmetic evaluation, 34 
blanks 12 
bugs 46 

command execution, 25 
comments 14 
compound commands 13 
control operators 12 
environments 25-26 
escape character, 14 
exit status 26 
expansion, 18-21 
files 46 
functions 23 
history list, 32-33 
invocation, 45-46 
job control, 24-25 
lists 12-13 
meta characters 12 
names 12 
options 11 


parameters 14-15 
pipdines(\), 12 
prompting, 26 
quoting, 14 
readline, 27-32 
redirection, 21-23 
reserved words 12 
she/I variables 15-18 
s'gnals 25 

ample commands 12 
words 12 

built-in commands, 35-45 
alias 35 
bg, 35 
bind, 35 
break, 35 
builtin, 35 
cd, 35-36 
command, 36 
continue, 36 
declare, 36 
dirs 36 
echo, 36-37 
enabling/disabling, 37 
a/a/, 37 
exec, 37 
exit, 37 
export, 37 
fc, 37-38 
fg,38 
getopts 38 
hash, 38 
help, 38 
history, 39 
jobs 39 
kill, 39 
let, 39 
local, 39 
logout, 39 
popd, 39-40 
pushd, 40 
pwd, 40 
read, 40 
readonly, 40 
return, 40 
set, 40-42 
shift, 42 


suqcend, 42-43 
test expr, 43 
times, 43 
trap, 43-44 
type, 44 
ulimit, 44-45 
umask, 45 
unalias 45 
unset, 45 
wait, 45 

commands, executing, 1047 
exiting, 37 
interactive, 45 
login, 45 
changing, 63 
exiting, 39 
pathnames 1186 
remote, 466-467 
server, 1385-1386 
suspending execution, 42-43 
user, getting, 946-947 
shells file, 1186 
shift (shell command), 42 
shlock, 487 

SH LVL variable (bash), 15 
shmctl, 849-851 
commands, 850 
errors, 851 
system calls, 851 
shmget, 851-853 
bugs, 853 
errors, 852 
system calls, 852 
shmop, 853-854 
show-all-if-ambiguous 
variable (readline), 28 
showmount, 1396 
showrgb, 488 
shrinkfile, 488 
shutdown, 855,1396-1397 
bugs, 1397 
errors, 855 
files, 1397 
options, 1397 
sigaction, 855-857 
sigaddset, 1019-1020 
sigblock, 858 
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sigdel set, 1019-1020 
sigemptyset, 1019-1020 
sigfillset, 1019-1020 
siggetmask, 858 
siginterrupt() function, 1019 
sigismember, 1019-1020 
sigmask, 858 

signal, 857-858,1248-1249 

bugs, 1249 

signal messages, printing, 

996 

signals 

available (list of), 1248-1249 

bash, 25 

blocked 

changing list of, 856 
releasing, 858-859 
changing process action, 
855-856 

describing with strings, 1038 
handling, 857-858 
interrupting system calls, 
1019 
masks 

manipulating, 858 
replacing, 856 
pending, examining, 856 
POSIX signal set operations, 
1019-1020 

sending to processes, raise 
function, 1000 
waiting for, 817 

signatures, tin, 528 
sigpause, 858-859 
sigpending, 855-857 
sigprocmask, 855-857 
sigreturn, 859 
sigsetmask, 858 
sigsuspend, 855-857 
sigvec, 860 

simple commands (bash), 12 
simpleinit, 1397-1399 

bugs, 1399 
files, 1398 

sin() function, 1020-1021 
sinh() function, 1021 
sirtopnm, 488-489 


site (ftp command), 152 
size, 489-490 
copying, 489-490 
ftp command, 152 
options, 489 
slattach, 1399 
sic command (telnet), 510 
sldtoppm, 490-491 
sleep() function, 1021 
sliplogin, 1399-1401 
diagnostics, 1400 
/etc/slip.hosts format, 1400 
example, 1400 
parameters, 1400 
smb filesystem, 1126 
sm proxy, 491-492 
snprintf function, 992-996 
SOCK DGRAM sockets, 
860-861 

SOCK RAW sockets, 861 
SOCK~RDM sockets, 861 
SOCK'SEQPACKET sockets, 
860-861 

SOCK STREAM sockets, 
860-861 
socket, 860-861 

errors, 861 
socket types, 860 
SOCK_DGRAM, 
860-861 

SOCK_RAW, 861 
SOCK_RDM, 861 
SOCKSEQPACKET, 
860-861 

SOCKJTREAM, 
860-~861 
socketcall, 862 
socketpair, 862-863 
sockets 
connections 

accepting, 740-741 
initiating, 752-753 
listening for, 792-793 
creating, 860-861 
names 

binding, 745-746 
getting, 769 


options, 770-771 

getting/setting, 769-772 
SO_BROAD CAST, 771 
SO_D EBUG, 770 
SO_DONTROUTE, 770 
SO_ERROR, 771 
SO_KEEPALIVE, 770 
SO_LINGER, 770 
SO_RCVBUF, 771 
SO_RCVLOWAT, 771 
SO_RCVTIMEO, 771 
SO_REUSEADDR, 770 
SO_SN D BU F, 771 
SOSNDLOWAT, 771 
SO_SNDTIM EO, 771 
SO TYPE, 771 
pairs, creating, 862-863 
peers, getting names, 765 
receiving messages from, 
826-828 

sending messages from, 
842-843 
system calls, 862 
types, 860 

SOCK_DGRAM, 
860-861 

SOCK_RAW, 861 
SOCK_RDM, 861 
SOCK_SEQPACKET, 
860-861 

SOCKJTREAM, 

860-861 

soft-reset() action (xterm), 
715 

Solitaire files, converting to 
portable anymaps, 488-489 
sort, 492-493 
sorted arrays, searching, 
900-901 

sorted files, removing 
duplicate lines, 560 
sorted word lists, compress¬ 
ing/uncompressing, 496 
sorting arrays, 1000 
sound drivers, boot-time 
parameters, 1224 
source command (xauth), 591 
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spaces, converting to tabs, 559 

spctoppm, 494 

special parameters, bash, 

14-15 

! (exclamation points), 15 
#(pound signs), 15 
$ (dollar signs), 15 
* (asterisks), 15 
- (hyphens), 15 
? (question marks), 15 
@ (at signs), 15 
_ (underscores), 15 
0,15 

spell-checking, 274, 280 

buildhash, 279 
findaffix, 280 
icombine, 281 
ijoin, 281 
ispell, 274-279 
ispell dictionaries, 

1084-1090 
affix file, 1084-1085 
alternate string characters 
1087 

character-st section, 1086 
flags 1088 
headers 1085 
optionsstatements 
1085-1086 

prefix/suffix tables, 1088 
root words 1084-1085 
munchlist, 279-280 
tryaffix, 281 

split, 494-495 

splitting files, 85-86,119-120 
spool queue 

examining, 298-299 
removing jobs from, 

301-302 

SPOT satellite images, 
converting to portable 
graymaps, 495 
spottopgm, 495 
sprintf function, 992-996 
sprintf() function, awk, 
167-168 

sputoppm, 495-496 


sq, 496 

sqrt() function, 1023 
square roots (returning), 1023 
srand() function, 1001 
srand48() functions, 912 
srandom() function, 
1001-1002 

sscanf function, 1013-1015 
st, 1096-1100 

ioctl( ) calls, 1097-1100 
return values, 1100 

stack, saving context, 1018 
standard colormap utility (X), 
699-700 

standard error output, 
redirecting, 22 
standard output, redirecting, 
22 

start-cursor-extend() action 
(xterm), 714 

start-extend() action (xterm), 
714 

startup time 

adjusting to GMT, 1424- 
1425 

converting, 1430 

startx, 496-497 
stat, 863-864 
statements, awk, 167-168 
states (system), updating, 
1414-1415 
staffs, 865-866 
status 
cvs, 102 
ftp, 152 

telnet command, 512 

stdarg, 1023-1024 
stdio library, 1025-1027 

bugs, 1026 

functions, 1026-1027 

stime, 866 

stpcpy() function, 1027-1028 
strcasecmp(), 1028 
strcat() function, 1028-1029 
strchr() function, 1029 
strcmp() function, 1029-1030 
strcoll() function, 1030 
strcpy() function, 1030-1031 


strcspn() function, 

1038-1039 

strdup() function, 1031 
stream-oriented editor, see sed 
streams 

binary, input/output 
(getting), 926-927 
block buffered, 1016 
buffering operations, 
1016-1017 

checking/resetting status, 
919-920 
closing, 919 
directory 

current location (return¬ 
ing), 1048 
resetting, 1011 
flushing, 920-921 
line buffered, 1016 
opening, 924-925 
repositioning, 927-928 
unbuffered, 1016 
strerror() function, 1032 
strfry(), 1032 
strftime() function, 
1032-1034 

conversion specifiers, 1033 
tm structure members, 1034 

string constants, awk, 

169-170 

string functions, awk, 169 
string variables, configura¬ 
tion-dependent, 906-907 
string!) action (xterm), 714 
strings, 498 
byte 

copying, 900 
operations 901 
writing zeros to, 902 
comparing, 1029-1030 
byte, 899-900 
ignoring case, 1028 
using current locale 1030 
concatenating, 1028-1029 
converting 
to doubles 898, 
1039-1040 
to integers 898-899 
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to long integers 899, 

1041 

to multibyte character 
(from wide character), 
1061 

to tm structure 
1036-1037 

to unsgned long integers 

1041-1042 

to wide character (from 
multibyttf, 917-918 
copying, 498,1030-1031 
ipcpy() function, 
1027-1028 

describing signalswith, 1038 
duplicating, 1031 
extracting tokens from, 
1037-1040 

length (calculating), 1035 
locating characters in, 953, 
1029 

options, 498 
outputting, 997-999 
randomizing, 1032 
searching, for character sets, 
1035-1039 

string operation functions, 
1034-1035 

transformation, 1042-1043 
see also substrings 

strip, 499 

strlen() function, 1035 
strncasecmp(), 1028 
strncat() function, 1028-1029 
strncmp() function, 

1029- 1030 
strncpy() function, 

1030- 1031 
strpbrk() function, 

1035- 1036 
strptime() function, 

1036- 1037 
bugs, 1037 

field descriptors, 1036-1037 

strrchr() function, 1029 
strsep() function, 1037-1038 
strsignal() function, 1038 
strspn() function, 1038-1039 



strstr() function, 1039 
strtod() function, 1039-1040 
strtok() function, 1040 
strtol() function, 1041 
strtoul() function, 1041-1042 
struct (ftp command), 152 
strxfrm() function, 

1042-1043 

subdirectories, MS-DOS 

creating, 326 
moving, 327 
removing, 329 
renaming, 329-330 
subroutines 

endnetent, 936-937 
getnetbyaddr, 936-937 
getnetbyname, 936-937 
getnetent, 936-937 
subst, 500-501 
substrings 
locating, 1039 
locating in memory areas, 
981 

see also strings 

suffixes, 1249-1252 
sum, 501 

Sun icons, converting to 
portable bitmaps, 262 
Sun raster files, converting to 
portable anymaps, 438 
SuperProbe, 501-503 
bugs, 503 
options, 502 
running, 502-503 
suspend (shell command), 
42-43 

suspending execution, 1061 
swab() function, 1043 
swap area, setting up, 
1327-1328 

swap device parameter, values, 
1374 

swapoff, 866-867,1401 

errors, 867 
files, 1401 
priority, 867 


swapon, 866-867,1401 

errors, 867 
files, 1401 
priority, 867 

swapping 

enabling/disabling, 1401 
starting/stopping, 866-867 
priority, 867 

swapping bytes, 1043 
symbolic links, 867-869 
reading values, 823-824 
symlink, 867-869 
sync, 869,1401-1402 
synchronizing files with 
memory maps, 811 
synchronous I/O, 
multiplexing, 835-837 
syscall macros, 738 
syscall() macros, 738 
sysconf() function, 

1043-1045 
sysctl, 869-871 
sysfs, 871 
sysinfo, 871-872 
sysklogd, 1402-1404 
configuration file, 1402- 
1403 

FIFOs, 1403 
files, 1404 
installing, 1403 
remote logging, 1403 
security, 1403-1404 
syslog, 872-874 
syslog() function, 1045-1046 
syslog.conf, 1186-1188 
action field, 1186-1187 
examples, 1187-1188 
facility keyword, 1187 
level keyword, 1187 
selector field, 1186-1187 
syslogd, 1404-1405 
configuration file, 1186- 
1188 

action field, 1186-1187 
examples 1187-1188 
facility keyword, 1187 
/eve/ keyword, 1187 
selector field, 1186-1187 
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files, 1405 
options, 1405 

system 

configuration, getting 
information at runtime, 
1043-1045 

displaying information 
about, 562 

load average, graphing, 533 
page size, getting, 765 
parameters, reading/writing, 
869-871 

printing activity summary, 
573 

shutting down, 1396-1397 
state, updating, 1414-1415 
status server, 1386-1387 
message format, 
1386-1387 

system (ftp command), 152 
system calls, 738-739 

calling directly, 738 
interrupting with signals, 
1019 
I PC,789 
obsolete, 814 
prototypes, 738 
socket, 862 
syscall macros, 738 
undocumented, 881 
unimplemented, 881-882 
system logging, 1402-1404 
configuration file, 
1402-1403 
FIFOs, 1403 

making log entries, 295-296 
messages, 1404-1405 
remote, 1403 
sending messages to, 
1045-1046 

System V interprocess 
communication, 1144-1146 

message queues, 1145 
resource access permissions, 
1144-1145 

semaphore sets, 1145-1146 
shared memory segments, 
1146 


System V I PC keys, convert¬ 
ing pathnames/project 
identifiers to, 929-930 
system!) function, 1047 
sysv filesystem, 1125 

T 

Tab Window M anager, see 
twm 
tables 

descriptor, size (getting), 
760-761 
file 

adding entries 
1428-1429 

description, 1425-1426 
initializing, 1427 
moving files to end, 1431 
removing files 1431-1432 
structure, 1426 
table entries 1426 
unreferenced entries 
(fetching), 1428 
hash 

creating, 951 
freeing memory, 951 
searching, 951 
IP routing (manipulating), 
1379-1380 

local descriptor, reading/ 
writing, 800 

RARP, manipulating, 1373 
troff, formatting, 236-237 

tabs, converting to spaces, 137 
tac, 503-504 

tag (cvs command), 102-103 
tag files 

emacs, 135-137 
generating, 87-88 
vi, 135-137 
tail, 504 
talk, 505 
talkd, 1405-1406 
tan() function, 1047-1048 
tanh() function, 1048 
teal, 506 


tcdrain(), 876,1052 
tcflow(), 876,1052 
teflushf), 876,1052 
tcgetattr(), 876,1051 
tcgetpgrpf), 877,1053 
tcsendbreak(), 876,1052 
tesetattrf), 876,1052 
tesetpgrpt), 877,1053 
tdelete, 1056-1058 
tek-copy() action (xterm), 

716 

tek-page() action (xterm), 

715 

tek-reset() action (xterm), 

716 

tel in it, 1307-1309 

diagnostics, 1309 
files, 1308 
run levels, 1308 

telldir() function, 1048 
telnet, 507-512 

commands, 508-512 
!, 512 
?, 512 
dose 508 

display argument, 508 
environ, 511 
mode, 508 
open host, 508 
quit, 508 

send arguments 508-509 

set, 509-510 

dc, 510 

status 512 

toggle 511-512 

unset, 509-510 

z, 512 

environment, 512 
files, 512 
options, 507 

Telnet protocol 

DARPA server, 1406-1407 
interface, see tel net 

telnetd, 1406-1407 
tempnam() function, 1049 
temporary filenames, creating, 
983-984 
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temporary files 

creating, 983,1053-1054 
naming, 1049,1054 

tenex (ftp command), 152 
termcap, 1188-1197 

Boolean capabilities, 1189 
numeric capabilities, 

1189- 1190 
string capabilities, 

1190- 1197 

control codes 1195-1196 

terminals 

attributes, 1049-1053 
getting, 876 
setting, 482-483, 876 
baud rate, 1049-1053 
capability database, 

1188-1197 

Boolean capabilities 1189 
numeric capabilities 

1189- 1190 
string capabilities 

1190- 1197 
controlling terminal, 

1100-1101 
creating typescript of 
sessions, 474-475 
displaying last login, 
285-286 

foreground processes, group 
ID, 1049-1053 
initializing, 539-542 
line control, 1049-1053 
name and device list, 1197 
names (returning), 1058 
resetting, 456 
serial lines, 1101 
termios functions, 874-878 
type mapping, 540-541 
type, setting in shell 
environment, 540 
virtual hangups, 885 
window size, setting, 
456-457 

terminating processes, 
283-284 


terminating programs 

abortf) function, 892 
assert() function, 895-896 
termios functions, 874 
flag constants, 874-876 
termios structure 

c_cflag flag constants, 1051 
cjflag flag constants, 1050 
cjflag flag constants, 1051 
c_oflag flag constants, 
1050-1051 

testexpr (shell command), 43 
text 

compressed, viewing, 
733-734 

filters, more, 327-328 
formatting line lengths, 143 
rendering to bitmaps, 
355-356 
sorting, 492-493 
editors, elvis, 126-128 
files 

converting for printing, 
429-430 

creating gcal resource files 
from, 558 

tfind, 1056-1058 
tfmtodit, 513 

TFTP (Trivial FileTransfer 
Protocol), 1407 

DARPA server, 1407 

tftp, 514-515 

TFTP (Trivial FileTransfer 
Protocol), 514 
tftpd, 1407 
tgatoppm, 515 
TI ACTIVEFILE environ¬ 
ment variable, 529 
TI_NOVROOTDIR environ¬ 
ment variable, 529 
TIFF files, converting to 
portable anymaps, 515-516 
tifftopnm, 515-516 
tilde expansion (bash), 19 
time 

calculating differences, 911 
getting/setting, 772-773 
in sconds 878 


returning current, 928-929 

setting, 866 

startup 

adjusting to GMT, 
1424-1425 
converting, 1430 

time functions, 878 

awk, 169 

timeserver daemon, 
1407-1408 
time zones 

compiling, 1419-1422 
printing, 1419 

time-sharing scheduling, 834 
timed, 1407-1409 

control program, 1408-1409 
files, 1408 

timedc, 1408-1409 
timers (event), managing, 

1424 

times 

binary, converting to ASCII, 
909-911 
converting 

to ASCII, 984-986 
initializing converson 
information, 986-988, 
1058-1060 
strings to numbers 
989-990 
to tm structure, 

1036-1037 
formatting, strftime() 
function, 1032-1034 
process, getting, 878-879 
time zone information files, 
1197-1198 

user/system, printing, 43 

times (shell command), 43 
times function, 878-879 
timestamps, changing, 536 
tin, 516-533 

articles 

automatic mailing, 528 
autoselect/autokill, 
526-527 
crosqooSting, 527 
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customizing quote string, 
527 

mailing, 527 
piping, 527 
posting, 527 
printing, 527 
saving, 527-528 
tagging/untagging, 528 
bugs, 531 
commands 

article viaver, 522-524 
editing, 519 

global options menu, 524- 
525 

group index, 521-522 
newsgroup selection, 
519-520 

spool direXory selection, 
520 

thread listing, 522 
environment variables, 
528-530 

ADD_ADDRESS, 529 
AUTOSUBSCRIBE, 529 
AUTOUNSUBSCRIBE, 
530 

BUG_ADDRESS, 529 
DISTRIBUTION, 529 
MAILER, 529 
NNTPSERVER, 529 
ORGANIZATION, 529 
REPLYTO, 529 
TI_ACTIVEFILE, 529 
TI_NOVROOTDIR, 529 
TIN_HOMEDIR, 528 
TIN JNDEXDIR, 529 
TIN-LIBDIR, 529 
TIN_SPOOLDIR, 529 
TINRC, 528 
VISUAL, 529 
files, 531 

group attributes, 526 
index files, 517-518 
moving between levels, 519 
news administration, 518 
options, 516-517 
screen format, 518-519 


signatures, 528 
starting, 518 

tinrc configurable variables, 
525-526 

xterm buttons, 530-531 

TINHOMEDIR 
environment variable, 528 
TININDEXDIR 
environment variable, 529 
TIN LIBDIR environment 
variable, 529 
TIN_SPOOLDIR 
environment variable, 529 
tinrc configurable variables, 
525-526 
seea/sotin 

TINRC environment variable, 
528 

tload, 533 

TMOUT variable (bash), 17 
/tmp directory, 1237 
tmpfile() function, 

1053-1054 

tmpnam() function, 1054 
toascii() function, 1055 
toggle command (telnet), 
511-512 

tokens, extracting from 
strings, 1037-1040 
tolower() function, 

1055-1056 
top, 533-535 
bugs, 535 

commands, 534-535 
field descriptions, 534 
options, 534 

topological sorting (graphs), 
542 

touch, 536 
toupper() function, 
1055-1056 
tr, 536-539 

character classes, 537-538 
escape characters, 537 
ranges, 537 

repeated characters, 537 
specifying character sets, 537 


squeezing/deleting, 538-539 
translating, 538 
warning messages, 539 

tr2tex, 1252-1253 
trace (ftp command), 152 
traceroute, 1409-1412 

examples, 1411 
options, 1410 

transforming strings, 
1042-1043 

translating/deleting charac¬ 
ters, 536-539 

trap (shell command), 43-44 
Trivial File Transfer Protocol, 
seeTFTP 
troff 

compiling pictures for, 
211-215 

converting to LaT eX, 
1252-1253 

formatting tables, 236-237 
output format, 1129-1131 

T rueVision T arga files, 
converting to portable 
pixmaps, 515 
truncate, 879-880 
tryaffix, 274, 281 
files, 281 
seea/so ispell 
tsearch, 1056-1058 
tset, 539-542 
compatibility, 542 
environment, 541 
files, 541 
options, 540 

setting environment, 540 
terminal type mapping, 
540-541 

tsort, 542 
tty, 1100-1101 
ttyname, 1058 
ttys, 1101 
ttytype, 1197 
tune2fs, 1412-1413 
tuneip, 1413-1414 
twalk, 1056-1058 
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twm, 542-557 

bindings, 552-553 
bugs, 557 

customizing, 543-544 
environment, 557 
files, 557 

functions, 554-556 
!, 554 

f.autorai^, 554 
f.backiconmgr, 554 
f.beep, 554 
f. bottom zoom, 554 
f.circledown, 554 
f.drcleup, 554 
f.colormap, 554 
f.deiconify, 554 
f. delete, 554 
f.de/tastop, 554 
f. destroy, 554 
f. down icon mgr, 554 
f.exec, 554 
f. focus 554 
f.forcemove 555 
f.forw icon mgr, 555 
f.fullzoom, 555 
f.funotion, 555 
f.hbzoom, 555 
f.hida'conmgr, 555 
f.horizoom, 555 
f.htzoom, 555 
f.hzoom, 555 
f.iconify, 555 
f.identify, 555 
f.lefticonmgr, 555 
f.leftzoom, 555 
flower, 555 
f.menu, 555 
f.move, 555 
f.ne<ticonmgr, 555 
f.nop, 555 
f.pr a/icon mgr, 555 
f.priority, 555 
f.quit, 555 
f.raise 555 
f.raiselower, 555 
f. refresh, 555 
f.reaze, 555 


f. restart, 555 
f.righticonmgr, 555 
f.rightzoom, 556 
f.saveyourse/f, 556 
f. show icon mgr, 556 
f.sorticonmgr, 556 
f.title, 556 
f.topzoom, 556 
tun focus 556 
f.upiconmgr, 556 
f.vizoom, 556 
f.vrzoom, 556 
f.warpring, 556 
f.warpto, 556 
f.warptoiconmgr, 556 
f.warptoscreen, 556 
f.winrefresh, 556 
f.zoom, 556 
icons, 557 
menus, 556-557 
options, 543 
starting, 543 
startup files, 543-544 
variables, 544-552 
AutoRaise 544 
AutoRdativeResze 

544-545 
BorderColor, 545 
BorderT ileBackground, 

545 

BorderT ileForeground, 

545 

BorderWidth, 545 
Button!ndent, 545 
CiientBorderWidth, 545 
Color, 545-546 
C onstrainedM oveT ime, 

546 

Cursors 546 
DecorateTransients 546 
DrfaultBackground, 546 
DrfaultForeground, 547 
D dauItFunction, 552 
D ontl conifyByU nmapping 

547 

DontM oveOff, 547 
D ontSqueszeTitle, 547 


Forcelcons 547 
FramePadding, 547 
Grayscale, 547 
IconBackground, 547 
I con BorderColor, 547 
IconBorderWidth, 547 
I con D i rectory, 547 
IconFont, 547 
IconForeground, 547 
I conifyByU nmapping, 

547 

IconM anagerBackground, 
547 

IconM anagerD ontShow, 

547 

IconM anagerFont, 548 
IconM anagerForeground, 

548 

I conM anagerG eometry, 
548 

IconM anagerFI ighlight, 

548 

IconM anagers 548 
IconM anagerShow, 548 
I con Region, 548 
Icons 548-549 
InterpolateM enuColors 

549 

M akeTitle, 549 
M axWindowSize 549 
M enuBackground, 549 
M enuFont, 549 
M enuForeground, 549 
M enuShadowColor, 549 
M enuT itleBackground, 
549 

M enuT itleForeground, 
549 

M onochrome, 549 
M oveDelta, 549 
N oBackingStore, 549 
N oCassSensitive, 549 
NoDefaults 549 
N oGrabServer, 549 
N ohl ighlight, 550 
N olconM anagers 550 
N oM enu Shadows 550 
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N oRaiasO nD dconify, 550 
NoRai^OnM ove 550 
NoRaisOnResze, 550 
NoRaiseOnWarp, 550 
N oSaveU riders, 550 
N oStackM ode, 550 
NoTitle 550 
N oTitltfocus 550 
N oT itleH ighlight, 550 
Opaqudvi ove, 550 
Pixmaps 550 
Priority, 550 
RandomPlacement, 550 
Resiztfont, 551 
RestartPreviousState 551 
SaveColor, 551 
ShowIconM anager, 551 
SortlconM anager, 551 
SqueseTitle, 551 
Startlconified, 551 
TitleBackground, 551 
T itleB uttonBorderW idth, 
551 

TitleFont, 552 
T itleForeground, 552 
TitlePadding, 552 
U n known I con, 552 
UsePPosition, 552 
WarpCursor, 552 
WarpU nmapped, 552 
WindowF unction, 552 
WindowRing, 552 
XorValue 552 
Zoom, 552 
windows, 543 
creating, 543 
resizing, 543 
txt2gcal, 558 
type 

ftp command, 152 
shell command, 44 

TZ environment variable, 987 
tzfile, 1197-1198 
tzset, 986-988 

files, 988 

TZ environment variable, 
987 

tzset() function, 1058-1060 


u 


UID variable (bash), 15 
ul, 558-559 

ulimit (shell command), 

44-45 

umask, 880 

ftp command, 152 
shell command, 45 

umsdos filesystem, 1125 
unalias (shell command), 45 
uname, 880-881 
unbuffered streams, 1016 
underlining, 558-559 
underscores! ), bash special 
parameters, 15 
undocumented system calls, 
881 

unexpand, 559 
ungetc() function, 945 
Unicode, 1065,1253-1255 

ASC11 -compatible encoding, 
1255-1256 

combining characters, 1254 
implementation levels, 1254 
Website, 1065 

unimplemented system calls, 
881-882 
uniq, 560 

Universal Product Code 
bitmaps, creating, 368 
UNIX 

copying MS-DOS files to/ 
from, 317-318 
filenames, restoring, 

324-325 
files, copying 

between ystems 563-565 
toMS-DOS,335 
unlink, 882 
unlocking memory 
munlock, 811-812 
munlockall, 812-813 
unmapping files to memory, 
799-800 


unmount, 802-804, 
1328-1332 

bugs, 1332 
errors, 803 
files, 1332 
options, 1331 
return value, 803 
unset 

shell command, 45 
telnet command, 509-510 

unshar, 560-561 
unsq, 496 

update (cvs command), 
103-104 

update_ state, 1414-1415 
updatedb, 561-562 
uppercase, converting letters 
to, 1055-1056 
uptime, 562 
uselib, 883 
Usenet 

administration, 1344-1346 
archiver, 1262-1263 
articles 

expiring, 1121-1123 
libinn routines 962-966 
purging, 1292-1293 
record of, 1131-1132 
retrieving fro NNTP 
server, 340-341 
sending to remote NNTP 
server, 1312-1313 
sending to remote site 
1349-1350 
goecitying distribution, 
1158-1163 

batch files, converting to 
INN, 1281-1282 
control messages, handling, 
1115-1116 
databases, recovering, 
1342-1344 
history file 

displaying filenames from, 
226-227 

removing filenames 
1370-1371 
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innwatch supervision, 
1142-1144 
log files, 1163-1165 
list of, 1164 

maintenance 1346-1347 
mesage'adion fields 
1163-1164 

moderated newsgroups, mail 
addresses, 1151-1152 
newsgroups, listing active, 
1104-1105 

sending articles to servers, 
267-269 

U senix FaceSaver files, 
converting to portable 
graymaps, 147 
user (ftp command), 152 
user group file, 1131 
user ID s (processes), setting, 
848-849 

real and effective, 847-848 

userlist, 563 
usernames 

getting, 934-935 
remote lookup, 1134-1135 

users 

adding to system, 

1258-1259 
displaying last login, 
285-286 

file permissions, checking, 
741-742 

IDs, getting, 773 
listing, 563 

logins, preventing, 1168 
outputting logged in 
on local machines 474 
on networks 472-473 
preference utility (X), 
690-693 

printing activity summary 
(w), 573 

quotas, editing, 1291-1292 
sending messages to, 473, 
576-577 

shells, getting, 946-947 
switching between, 296 



talking to online, 505 
writing messages to, 574, 
1383 

usleep() function, 1061 
/usr directory, 1237 
/usr/XHR6 directory, 1237 
/usr/XHR6/bin directory, 
1237 

/usr/XHR6/lib directory, 

1237 

/usr/XHR6/lib/Xll directory, 
1237 

/usrXHR6/indude/Xll 
directory, 1237 
ustat, 883-884 
UTF-8,1255-1256 
examples, 1256 
properties, 1255-1256 
utime, 884-885 
utimes, 884-885 
utmp, 1198-1200 
utmp file entries, accessi ng, 
947-948 

utmp/wtmp entries, manag¬ 
ing, 480-481 

utmpname() function, 947 
uucico, 1415-1417 

files, 1416-1417 
options, 1415-1416 

uucp, 563-565 

bugs, 565 

execution daemon, 572 
files, 564-565 
options, 564 

remote command execution, 
569-571 

status inquiry, 566-569 

UUCP 

connections, receiving news, 
463-464 

file transfer requests, 
processing, 1415-1417 

uudecode, 565-566 
uuencode, 565-566,1200 
uustat, 566-569 

examples, 568-569 
files, 569 
options, 567-568 


uux, 569-571 

bugs, 571 
examples, 571 
files, 571 
options, 570-571 
restrictions, 571 
uuxqt, 572 

V 

variable argument lists 
(declaring), 1023-1024 
variables 

awk, 163-165 
arrays 164 
built-in, 163-164 
typing and convert on, 
164-165 
bash, 15-18 
allow-null_glob 
_ expan son, 17 
autojesume, 18 
BASH,15 

BASH _VERSION, 15 
cdable_vars 18 
CDPATH,16 
command_ oriented_ hiiory, 

17 

ENV, 16 
EUID,15 
FCEDIT, 17 
FIGNORE, 17 
glob_dot_ filenames 17 
histchars 17-18 
HISTCMD, 16 
HISTFILE, 17 
HISTFILESIZE, 17 
HIST SIZE, 17 
HOME, 16 

hostname_ completion_ file, 

18 

HOSTTYPE, 16 
IFS, 16 

IGNOREEOF, 17 
INPUTRC, 17 
LINENO, 15 
MAIL, 16 
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MAIL_WARNING, 16 
MAILCHECK, 16 
MAILPATH, 16 
no_ exi t_ on_ failed_ exec, 

18 

noclobber, 18 
nolinks 18 
notify, 17 
OLDPWD, 15 
OPTARG,16 
OPTERR, 17 
OPTIND, 16 
OSTYPE, 16 
PATH,16 
PPID, 15-17 
PROMPT _COMM AND, 
17 

PS1, 16 
P52, 16 
PS3,17 
PS4, 17 
PWD, 15 
RANDOM, 15 
REPLY, 15 
SECONDS, 15 
SHLVL, 15 
TMOUT, 17 
UID,15 
declaring, 36 
local, creating, 39 
readline, 28 
bell-style, 28 
comment-begin, 28 
completion-query-items, 

28 

convert-mdta, 28 
editing-mode 28 
expand-tilde, 28 
horizontal-scroll-mode 28 
ke/map, 28 

mark-modified-lines 28 
meta-flag, 28 
output-meta, 28 
diow-all-if-ambiguous 28 
string, configuration- 
dependent, 906-907 


vcs, 1101-1102 
vcsa, 1101-1102 
vectors, reading/writing, 
824-825 

verbose (ftp command), 152 
vfat filesystem, 1125 

case sensitivity (mtools and), 
332 

vfork, 758 

vfprintf function, 992-996 
vfscanf function, 1013-1015 
vhangup, 885 
vi, seeeivis 

video hardware, identifying, 
501-503 

video mode tuner (XFree86), 
719-720 
buttons, 719 
moving display, 719 
options, 720 
vidr, 303-304 
view, seeeivis 
vipw, 1418-1419 
virtual 8086 mode, entering, 
885-886 

virtual consoles, 1066 

memory, 1101-1102 

virtual framebuffer X server, 
717-718 
virtual memory 

addresses, remapping, 
805-806 

reports, 1417-1418 

VISUAL environment 
variable, 529 

visual-beil() action (xterm), 
716 

vm86, 885-886 
vmstat, 1417-1418 
volume labels (M S-D OS), 
creating, 325-326 
vprintf function, 992-996 
vscanf function, 1013-1015 
vsnprintf function, 992-996 
vsprintf function, 992-996 
vsscanf function, 1013-1015 


w 

w, 573 

wait, 886-888 

errors, 887 
shell command, 45 
status macros, 887 

wait3, 888-889 
wait4, 888-889 
waitpid, 886-888 
wall, 574 
wc, 574 

wcstomb() function, 
1061-1062 

wcstombs() function, 1061 
Web sites, Unicode, 1065 
whereis, 575-576 
while (bash command), 13 
wide character stri ngs, 
converting to multibyte 
character strings, 1061 
wide characters, converting to 
multibyte characters, 
1061-1062 
widgets 

bitmap application, 54-57 
editres, 125-126 
xdipboard, 596 
xdock, 595 
xconsole, 598 
xcutsel, 599 

xdm authentication widget, 
609-610 

actions supported, 610 
resources 609-610 
xfd, 634-635 
xlogo, 668 
xmag, 671 
windows; X 

dumping utility, 721-722 
information utility, 722-724 

word splitting (bash), 21 
words 

bash, 12 

finding first bit set, 921 
input/output, 948 
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wrapping input lines, 143-144 

write, 576-577, 889-890 

errors, 889-890 

writev, 824-825,1003-1004 

bugs, 1004 
errors, 825,1004 

wtmp, 1198-1200 

X 

X Color Management System, 
D evice C olor C haracteriza- 
tion utility, 592-593 

X commands, grops, 232-233 

X font servers 

displaying information 
about, 145 

generating BD F fonts, 
146-147 

listing fonts, 145-146 

X sessions, initializing, 
496-497 

X Window System 

clients 

clipboard client, 595-597 
listing applications 
669-670 
clock, 593-595 
D isplay M anager, 599-614 
authentication widget, 
609-610 
chooser, 607 
configuration file 606 
controlling, 613 
environment variables 
608 

files 613 
limitations 613 
local server specification, 
607-608 
options 600-601 
reset program, 612 
resources 601-606 
resources file, 608 
server control, 612-613 
session program, 611-612 
sess'ons 600 


setup program, 608-609 
startup program, 610-611 
XDMCP service access 
control, 606-607 
emacs, 131-132 
fonts 

diqolaying all characters 
in, 633-636 
listing, 670-671 
image displayer, 725-726 
environment, 726 
options 725-726 
imake, 266 
initializer, 664-666 
keymaps, modifying, 
672-676 

LBX proxy server, 286-287 
logo, 667-668 
magnifying screen, 671-672 
monitoring system console 
messages, 597-598 
property displayer, 677-681 
constructing formats 679 
examples 680 
format characters 679 
sleeting windows 678 
remote program starts, 676 
resource database utility, 
681-684 

file symbols 681-682 
options 682-684 
root window parameters 
(setting), 693-694 
screen, refreshing, 684-685 
server information utility, 
614 
servers 

access control program, 
643-645 

diqolay server, 685-690 
font server, 641-643 
killing clients 666-667 
virtual framebuffer, 
717-718 

XFree86, 636-641 
Session M anager, 694-698 
default startup applica¬ 


tions 695 
options 695-698 
proxy, 698 

remote applications 698 
Session menu, 695-696 
SM _SAVE_D IR 
environment variable 
695 

starting sess'ons 695 
tester, 698-699 
.xsssaon file, 695 
standard colormap utility, 
699-700 

Tab Window M anager, 
542-557 

bindings 552-553 
bugs 557 

customizing, 543-544 
functions 554-556 
icons 557 
menus 556-557 
options 543 
starting, 543 
startup files 543-544 
variables, 544-552 
windows 543 

terminal emulator, 700-717 
actions 713-716 
character classes 712-713 
emulations 700 
environment, 717 
features 700-701 
menus 711-712 
options 701-705 
pointer usage, 710-711 
resources 705-710 
security, 712 
user preference utility, 
690-693 

window dumping utility, 

721- 722 

window information utility, 

722- 724 

X10 bitmaps, converting to 
portable, 592 

Xll bitmaps, converting to 
portable, 592 
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Xll pixmaps, converting to 
portable, 677 
Xll server 

performance comparison 
program, 585-586 
performance test program, 
577-585 

X11/X10 window dump files, 
converting to portable 
anymaps, 722 
xllperf, 577-585 
options, 578-585 
xllperfcomp, 585-586 
xargs, 586-587 
xauth, 587-592 
bugs, 592 

commands, 588, 591 
?, 591 
exit, 591 
help, 591 
info, 591 
list, 591 
merge, 591 
quit, 591 
remove, 591 
source 591 
display names, 591 
environment, 589 
environment variables, 592 
example, 591 
files, 589, 592 
generating magic cookies 
for, 317 

options, 587-588 

xbmtopbm, 592 
xdipboard, 595-597 

buttons, 596 
environment, 597 
files, 597 
options, 596 

sending/retrieving contents, 
596-597 
widgets, 596 
xdock, 593-595 
bugs, 595 
defaults, 594-595 
environment, 595 


files, 595 
options, 594 
widgets, 595 

xcmsdb, 592-593 
xconsole, 597-598 
xcutsel, 598-599 
Xdf disks, 332 
xdm, 599-614 

authentication widget, 
609-610 

actions supported, 610 
resources 609-610 
chooser, 607 
configuration file, 606 
controlling, 613 
environment variables, 608 
files, 613 
limitations, 613 
local server specification, 
607-608 

options, 600-601 
reset program, 612 
resources, 601-606 
D isplayM anager., 604 
D isplayM anager. accesf He 
603 

D isplayM anager.authD ir, 
602 

DiqolayM anager.autoResan, 
602 

D itfayM anags.chdcET imeout 
603 

D iplayM anags.daenonM ode 
602 

D iqolayM anager. debug, e/el, 
602 

D isplayM anager.D I SPLAY. 

authComplain, 605 
D isplayM anager.D I SPLAY. 

authFile 605 
D isplayM anager.D I SPLAY. 

authN ame, 605 
D isplayM anager.D ISPLAY. 

authorize 605 
D isplayM anager.D ISPLAY. 
chooser, 603 


D isplayM anager.D ISPLA Y. 
cpp, 603 

D isplayM anager.D ISPLA Y. 

failsafeClient, 605 
D isplayM anager.D ISPLA Y. 

grabServer, 605 
D isplayM anager.D ISPLA Y. 

grabT imeout, 605 
D isplayM anager.D ISPLA Y. 

openD day, 604 
D isplayM anager.D ISPLA Y. 

open Repeat, 604 
D isplayM anager.D ISPLA Y. 

openTimeout, 604 
D isplayM anager.D ISPLA Y. 

pingl nterval, 604 
D isplayM anager.D ISPLA Y. 

pingT imeout, 604 
D isplayM anager.D ISPLA Y. 
rest, 604 

D isplayM anager.D ISPLA Y. 

resetForAuth, 606 
D isplayM anager.D ISPLA Y. 

resetSignal, 605 
D isplayM anager.D ISPLA Y. 

resources 603 
D isplayM anager.D ISPLA Y. 
9 ssaon, 603 

D isplayM anager.D ISPLA Y. 
stup, 603 

D isplayM anager.D ISPLA Y. 
startup, 603 

D isplayM anager.D ISPLA Y. 

syStemPath, 604-605 
D isplayM anager.D ISPLA Y. 

syStemShell, 605 
D isplayM anager.D ISPLA Y. 

terminateServer, 604 
D isplayM anager.D ISPLA Y. 

termSignal, 605 
D isplayM anager.D ISPLA Y. 

userAuthD ir, 606 
D isplayM anager.D ISPLA Y. 

usrPath, 604 
D isplayM anager.D ISPLA Y. 
xrdb, 603 
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D igdayM anager.errorL of He 
602 

DigelayM anager.exportList, 
603 

D isplayM anager.greeterLib, 
603 

D igelayM anager.keyFile 
602 

D isplayM anagsr.lockPidFile 
602 

D igelayM anager.pidFile 
602 

DigolayM anager.randomFile 
603 

D igelayM anager. remove 
D omainname, 602 

DigelayM anager.requestPort, 
601 

D iplayM anager.servers 
601 

resources file, 608 
server control, 612-613 
session program, 611-612 
sessions, 600 
setup program, 608-609 
startup program, 610-611 
XD M CP service access 
control, 606-607 
XD M CP service, access 
control, 606-607 
xdpyinfo, 614 
XF86_8514 server, 615 
XF86 Accel, 614-623 
bugs, 623 

configuration, 615-616 
files, 622 
options, 616 
setup, 616-622 

XF86 AGX server, 615 
XF86~Mach32 server, 615 
XF86_Mach64 server, 615 
XF86 Mach8 server, 615 
XF86~Mono, 624-627 
configuration, 624 
files, 626 
options, 624 
setup, 624-626 


XF86 P9000 server, 615 
XF86 S3 server, 615 
XF86~SVGA, 627-631 

configuration, 627-628 
files, 630-631 
options, 628 
setup, 628-630 

XF86 VGA16, 631-633 

configuration, 631 
files, 633 
options, 632 
setup, 632 

XF86 W32 server, 615 
XF86Config, 1201-1208 

Device sections, 1204-1206 
Files section, 1201 
Keyboard section, 1202 
M onitor sections, 
1203-1204 

Pointer section, 1202-1203 
Screen sections, 1206-1208 
ServerFlags section, 1201 

xf86config, 633 
xfd, 633-636 

application-specific 
resources, 635 
bugs, 636 

fontgrid resources, 635 
options, 634 
widgets, 634-635 
XFree86, 636-641 
configuration, 636 
configuration file, 
1201-1208 
D e/ice sections 1204- 
1206 

Filessection, 1201 
Keyboard section, 1202 
M onitor sections 
1203-1204 
Pointer section, 
1202-1203 
Screen sections 
1206-1208 

ServerFlagssection, 1201 
environment variables, 637 
key combinations, 638 


network connections, 
636-637 

options, 637-638 
setup, 638 

video modetuner, 719-720 
buttons 719 
moving display, 719 
options 720 

xfs, 641-643 

bugs, 643 
configuration, 642 
naming, 643 
options, 641 
signals, 641 
xhost, 643-645 
bugs, 644 
diagnostics, 644 
environment, 644 
files, 644 
names, 644 
options, 643-644 
xiafs filesystem, 1125 
XIE protocol, testing, 
645-654 
xieperf, 645-654 
bugs, 654 
options, 646-654 
XIM files, converting to 
portable pixmaps, 654 
ximtoppm, 654 
xinetd, 655-664 
bugs, 664 

configuration file, 656-660 
editing signal responses, 
660-661 
files, 663 

internal services, 660 
log format, 661-663 
options, 655-656 
xinit, 664-666 

environment variables, 666 
examples, 665-666 
files, 666 
xkill, 666-667 
xlogo, 667-668 

environment variables, 668 
resources, 668 
widgets, 668 
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xlsatoms, 668-669 
xlsclients, 669-670 
xlsfonts, 670-671 
xmag, 671-672 
xmkmf, 672 
xmodmap, 672-676 
bugs, 675 
environment, 675 
examples, 674-675 
expression grammar, 
673-674 
options, 673 
xon, 676 
xpmtoppm, 677 
xprop, 677-681 

constructing formats, 679 
environment, 680 
examples, 680 
format characters, 679 
options, 677-678 
selecting windows, 678 
xrdb, 681-684 
bugs, 684 
environment, 684 
file symbols, 681-682 
options, 682-684 
xrefresh, 684-685 
arguments, 684-685 
bugs, 685 
defaults, 685 
environment, 685 
X resources file, 608 
Xserver, 685-690 
file utility, 587-592 
files, 690 
fonts, 689 
options, 686-687 

network connections 688 
server-depen dent, 
687-688 
XDMCP, 688 
XKEYBOARD,688 
security, 688-689 
signals, 689 
starting, 685 


xset, 690-693 
xsetroot, 693-694 
xsm, 694-698 

default startup applications, 
695 

options, 695-698 
proxy, 698 

remote applications, 698 
Session menu, 695-696 
SM_SAVE_DIR environ¬ 
ment variable, 695 
starting sessions, 695 
tester, 698-699 
.xsession file, 695 
xsmdient, 698-699 
xstdemap, 699-700 
xterm, 700-717 
actions, 713-716 

allow-snd-events( ), 714 
belli), 713 

dear-saved-lines(), 715 
hard-reset(), 715 
ignore! >, 713 
insert!), 713 
insrt-eght-bit(), 713 
insrt-sledion(), 713 
insrt-SB/en-bit(), 713 
kfymapf), 713 
popup-menu!), 713 
qui t(), 714 
redraw(), 714 
scroii-backO, 714 
9croll-forw(), 714 
secure!), 713 
sled-cursor-end, 714 
soled-cursor-start(), 714 
se/ed-end(), 714 
se/ed-extendf), 714 
se/ed-start!), 714 
send-s'gnali), 714 
sd-aiiowl32(), 715 
st-altsreen(), 715 
sat-appcursor(), 715 
set-appkeypad(), 715 


sst-autolinefeedf), 715 
sst-autowrap(), 715 
st-curssmul(), 715 
9et-jumpscroll(), 715 
set-marginbe/l(), 715 
st-re/ers-video(), 715 
st-re/erswrap(), 715 
set-scroll-on-key(), 715 
sat-scroll-on-tty-output(), 
715 

st-scroll barf), 715 
st-tek-text( >,715 
st-terminal-type(), 715 
set-visibility!), 715 
set-visual-bdl(), 715 
sat-vt-fontf), 714 
soft-re9at(), 715 
start-cursor-extend(), 714 
start-extendf), 714 
string!), 714 
tek-copy(), 716 
tek-page(), 715 
tek-reset!), 716 
visual-be/l(), 716 
bugs, 717 

character classes, 712-713 
emulations, 700 
environment, 717 
features, 700-701 
menus, 711-712 
options, 701-705 
pointer usage, 710-711 
resources, 705-710 
fontM enu entries 710 
mainM enu entries 709 
tekM enu entries 710 
vtMenu entries 709-710 
security, 712 
XV thumbnail pictures, 
converting to portable 
pixmaps, 720 
Xvfb, 717-718 
xvidtune, 719-720 
xvminitoppm, 720 
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xwd, 721-722 
xwdtopnm, 722 
xwininfo, 722-724 
xwud, 725-726 

Y 


y0() function, 959 
yl() function, 959 
ybmtopbm, 726 
yn() function, 959 
ytalk, 727-730 

Boolean options, 729 
daemons, 727 
escape menu, 728 
files, 730 
readdressing, 729 
runtime options, 728-729 
startup file, 729 
username field, 727 
Xll interface, 730 
YU V bytes, converting to 
portable pixmaps, 731 
YU V files, converting to 
portable pixmaps, 730-731 
yuvplittoppm, 730-731 
yuvtoppm, 731 

z 


zic, 1419-1422 

files, 1422 

link lines, 1421-1422 
options, 1419-1420 
rule lines, 1420-1421 
zone lines, 1421 

zmore, 733-734 
znew, 734-735 


z command (telnet), 512 
Z files, recompressing to GZ, 
734-735 
zcat, 248-249 
see a/so gzip 
zcatgzip, 248-249 
see a/so gzip 
zcmp, 731-732 
zdiff, 731-732 
zdump, 1419 

Zeissconfocal files, converting 
to portable anymaps, 732 
zeisstopnm, 732 
zero, 1094 
zforce, 732-733 
zgrep, 733 









